CLI Reference¶

The entry point for all commands is context-teleport. It operates as a single smart dispatch: when invoked in a TTY with arguments it runs the CLI, when invoked non-interactively with no arguments it starts the MCP server.

Most commands accept --format json (short: -F json) for machine-readable output. The watch command is an exception (foreground streaming process).

CLI vs MCP response conventions

The CLI and MCP server produce identical store side-effects (same files written, same entries created) but use different status strings in their responses. MCP write tools uniformly return "status": "ok" and remove tools return "status": "removed", following the convention for machine-to-machine communication. The CLI uses human-readable descriptive statuses (e.g. "checked_in", "written") in its text output. This asymmetry is intentional: both interfaces drive the same ContextStore methods, so the on-disk result is identical regardless of which interface is used.

Global Options¶

Option	Short	Description
`--format`	`-F`	Output format: `json` or `text` (default: `text`)
`--help`		Show help for any command

Top-Level Commands¶

init¶

Initialize a context store in the current project directory.

context-teleport init [--name PROJECT_NAME] [--repo-url URL]

Option	Short	Default	Description
`--name`	`-n`	directory name	Project name
`--repo-url`		`""`	Git remote URL

Creates the .context-teleport/ directory with manifest.json, knowledge/, knowledge/decisions/, conventions/, skills/, and supporting files.

Auto-initialization

When the MCP server starts in a git repository that has no .context-teleport/ directory, it automatically initializes the store using the directory name as the project name. No explicit init is needed for MCP usage.

Manifest auto-detection

During init, Context Teleport scans the project root for common marker files (pyproject.toml, Cargo.toml, package.json, CMakeLists.txt, go.mod, etc.) and auto-populates the languages and build_systems fields in the manifest. This information is surfaced in onboarding instructions as "Project stack" so agents immediately know the tech stack without scanning the filesystem.

Tip

If the project root contains EDA markers (LibreLane config, Makefile with OpenROAD, Liberty files), init will print detected EDA project information.

status¶

Show store state, sync status, and adapter info.

context-teleport status

Displays project name, schema version, knowledge count, convention count, decision count, skill count, current task, blockers, and enabled adapters. Also runs EDA project detection if markers are present.

get¶

Read any value by dotpath. Outputs JSON by default (designed for agent use).

context-teleport get <dotpath>

Argument	Description
`dotpath`	Path using dot notation (e.g. `knowledge.architecture`, `state.current_task`)

# Read a knowledge entry
context-teleport get knowledge.architecture

# Read the current task
context-teleport get state.current_task

set¶

Write any value by dotpath. Outputs JSON by default.

context-teleport set <dotpath> <value>

Argument	Description
`dotpath`	Path using dot notation
`value`	Value to set

context-teleport set knowledge.stack "Python 3.12, FastAPI"
context-teleport set state.current_task "Implement auth module"

search¶

Full-text search across all context.

context-teleport search <query> [--json]

Argument / Option	Description
`query`	Search query string
`--json`	Force JSON output (alternative to `--format json`)

Returns matching lines with key, line number, match text, and relevance score.

summary¶

One-page context summary optimized for LLM context windows. Includes knowledge entries, decisions, current state, and recent sessions.

context-teleport summary

push¶

Stage context changes, commit, and push to remote. Top-level shortcut for sync push.

context-teleport push [-m MESSAGE]

Option	Short	Description
`--message`	`-m`	Commit message (auto-generated if omitted)

If no remote is configured, the command commits locally and reports status: committed.

pull¶

Pull remote context and merge. Top-level shortcut for sync pull.

context-teleport pull [-s STRATEGY]

Option	Short	Default	Description
`--strategy`	`-s`	`ours` (or config value)	Merge strategy: `ours`, `theirs`, `interactive`, `agent`

When using interactive strategy, the CLI walks through each conflict in a TUI. Falls back to ours in non-interactive (piped) mode.

Tip

Set a default strategy with context-teleport config set default_strategy theirs to avoid passing -s every time.

diff¶

Show context changes. Top-level shortcut for sync diff.

context-teleport diff [--remote]

Option	Description
`--remote`	Compare local context with remote

log¶

Show context commit history. Top-level shortcut for sync log.

context-teleport log [--oneline] [-n COUNT]

Option	Short	Default	Description
`--oneline`		`false`	One-line format
`-n`		`10`	Number of entries to show

register¶

Register the Context Teleport MCP server with one or more AI coding tools. Auto-detects installed tools when no tool is specified.

context-teleport register [TOOL] [--local]

Argument / Option	Description
`TOOL`	Tool name: `claude-code`, `opencode`, `codex`, `gemini`, `cursor`. Omit to auto-detect.
`--local`	Use local `context-teleport` command instead of `uvx` (for development installs)

# Auto-detect and register all available tools
context-teleport register

# Register for a specific tool
context-teleport register claude-code

# Use local install instead of uvx
context-teleport register --local

unregister¶

Remove MCP server registration from one or all detected tools.

context-teleport unregister [TOOL]

Argument	Description
`TOOL`	Tool name. Omit to unregister from all detected tools.

watch¶

Monitor the context store for file changes and auto-commit/push via git. Uses watchdog for filesystem events if installed, falls back to polling. Press Ctrl+C to stop (performs a final sync before exiting).

context-teleport watch [--debounce SECONDS] [--interval SECONDS] [--no-push]

Option	Short	Default	Description
`--debounce`	`-d`	`5.0`	Seconds to wait after last change before syncing
`--interval`	`-i`	`2.0`	Polling interval in seconds (polling mode only)
`--no-push`		`false`	Only commit locally, do not push to remote

Subcommand Groups¶

knowledge¶

Manage knowledge entries. Prefix: context-teleport knowledge.

list¶

context-teleport knowledge list [--scope public|private|ephemeral]

Option	Short	Description
`--scope`	`-s`	Filter by scope

get¶

context-teleport knowledge get <key>

Argument	Description
`key`	Knowledge entry key

set¶

context-teleport knowledge set <key> [content] [--file PATH] [--scope SCOPE]

Argument / Option	Short	Description
`key`		Knowledge entry key
`content`		Content string (reads stdin if omitted and no `--file`)
`--file`	`-f`	Read content from file
`--scope`	`-s`	Scope: `public`, `private`, `ephemeral`

rm¶

context-teleport knowledge rm <key>

scope¶

context-teleport knowledge scope <key> <scope>

Argument	Description
`key`	Knowledge entry key
`scope`	New scope: `public`, `private`, `ephemeral`

search¶

context-teleport knowledge search <query>

Full-text search within knowledge files only. Returns key, line number, and matched text.

decision¶

Manage decision records (Architecture Decision Records). Prefix: context-teleport decision.

list¶

context-teleport decision list [--scope public|private|ephemeral]

Option	Short	Description
`--scope`	`-s`	Filter by scope

get¶

context-teleport decision get <id_or_title>

Argument	Description
`id_or_title`	Decision ID (integer) or title string for fuzzy match

add¶

context-teleport decision add <title> [--file PATH] [--scope SCOPE]

Argument / Option	Short	Description
`title`		Decision title
`--file`	`-f`	Read ADR content from a markdown file
`--scope`	`-s`	Scope: `public`, `private`, `ephemeral`

When neither --file nor stdin is provided, opens $EDITOR (default: vi) with a markdown template containing Context, Decision, and Consequences sections.

convention¶

Manage team conventions. Prefix: context-teleport convention.

list¶

context-teleport convention list [--scope public|private|ephemeral]

Option	Short	Description
`--scope`	`-s`	Filter by scope

get¶

context-teleport convention get <key>

Argument	Description
`key`	Convention key

add¶

context-teleport convention add <key> [content] [--file PATH] [--scope SCOPE]

Argument / Option	Short	Description
`key`		Convention key
`content`		Content string (reads stdin if omitted and no `--file`)
`--file`	`-f`	Read content from file
`--scope`	`-s`	Scope: `public`, `private`, `ephemeral`

rm¶

context-teleport convention rm <key>

scope¶

context-teleport convention scope <key> <scope>

Argument	Description
`key`	Convention key
`scope`	New scope: `public`, `private`, `ephemeral`

activity¶

Manage the team activity board. Prefix: context-teleport activity.

list¶

context-teleport activity list

Displays a table of active team members with their current task, issue reference, agent name, and staleness indicator. Entries older than 48 hours are marked as stale.

check-in¶

context-teleport activity check-in <task> [--issue REF]

Argument / Option	Short	Description
`task`		What you are working on
`--issue`	`-i`	Issue reference (e.g. `#42`)

Registers the current user on the activity board. The member name, agent, and machine are detected automatically.

check-out¶

context-teleport activity check-out

Removes the current user from the activity board. Returns an error if no active check-in exists for this user.

skill¶

Manage agent skills (SKILL.md files). Prefix: context-teleport skill.

list¶

context-teleport skill list [--scope public|private|ephemeral]

Option	Short	Description
`--scope`	`-s`	Filter by scope

get¶

context-teleport skill get <name>

Prints the full SKILL.md content (YAML frontmatter + markdown body).

add¶

context-teleport skill add <name> [--file PATH] [--description TEXT] [--scope SCOPE]

Argument / Option	Short	Description
`name`		Skill name (used as directory name under `skills/`)
`--file`	`-f`	Read SKILL.md content from file
`--description`	`-d`	Skill description (used in auto-generated frontmatter)
`--scope`	`-s`	Scope: `public`, `private`, `ephemeral`

When no file or stdin is provided, generates a template with YAML frontmatter.

rm¶

context-teleport skill rm <name>

scope¶

context-teleport skill scope <name> <scope>

Argument	Description
`name`	Skill name
`scope`	New scope: `public`, `private`, `ephemeral`

stats¶

Show usage and feedback statistics for all skills.

context-teleport skill stats [--sort usage|rating|name]

Option	Default	Description
`--sort`	`name`	Sort order: `usage`, `rating`, `name`

Displays a table with columns: name, usage count, average rating, rating count, last used date, and attention flag (! if the skill needs review).

feedback¶

List feedback entries for a specific skill.

context-teleport skill feedback <name>

Displays agent, rating (1-5), comment, and timestamp for each feedback entry.

review¶

Show skills needing attention (average rating below 3.0 with 2 or more ratings).

context-teleport skill review

For each flagged skill, shows average rating, rating count, usage count, and the three most recent feedback entries.

proposals¶

List skill improvement proposals.

context-teleport skill proposals [--skill NAME] [--status STATUS]

Option	Description
`--skill`	Filter by skill name
`--status`	Filter by status: `pending`, `accepted`, `rejected`, `upstream`

apply-proposal¶

Accept or reject a skill improvement proposal.

context-teleport skill apply-proposal <skill> <id> [--reject]

Argument / Option	Description
`skill`	Skill name
`id`	Proposal ID (full UUID or unambiguous prefix)
`--reject`	Reject instead of accept

When accepted, the proposal content replaces the current SKILL.md.

propose-upstream¶

Push an accepted proposal as a pull request to an upstream skills pack repository.

context-teleport skill propose-upstream <skill> <id> --repo OWNER/REPO

Argument / Option	Description
`skill`	Skill name
`id`	Proposal ID (full UUID or unambiguous prefix)
`--repo`	Target repository in `OWNER/REPO` format (required)

Clones the target repo, creates a branch (skill-improve/<name>-<short_id>), writes the proposed SKILL.md, commits, pushes, and opens a PR via gh pr create. Updates the proposal status to upstream on success.

Tip

Requires gh CLI to be installed and authenticated.

state¶

Manage ephemeral session state. Prefix: context-teleport state.

show¶

context-teleport state show

Displays current task, blockers, progress, last agent, last machine, and update timestamp.

set¶

context-teleport state set <key> <value>

Argument	Description
`key`	State field: `current_task`, `blockers` (comma-separated), `last_agent`, `last_machine`, or any custom key (stored in `progress` dict)
`value`	Value to set

clear¶

context-teleport state clear

Resets all ephemeral session state to defaults.

sync¶

Git-backed sync commands. Prefix: context-teleport sync. These are also available as top-level shortcuts (push, pull, diff, log).

push¶

context-teleport sync push [-m MESSAGE]

Stage context changes in .context-teleport/, commit, and push.

pull¶

context-teleport sync pull [-s STRATEGY]

Pull remote context and merge. Uses section-level merge for markdown files before falling back to the chosen strategy.

Option	Short	Default	Description
`--strategy`	`-s`	`ours` (or config)	`ours`, `theirs`, `interactive`, `agent`

resolve¶

context-teleport sync resolve [-s STRATEGY]

Retry merge resolution for pending conflicts. Only supports ours and theirs.

Option	Short	Default	Description
`--strategy`	`-s`	`ours`	`ours` or `theirs`

Tip

For interactive resolution, use context-teleport pull --strategy interactive instead. The resolve command is for automated conflict resolution.

diff¶

context-teleport sync diff [--remote]

log¶

context-teleport sync log [--oneline] [-n COUNT]

import¶

Import context from external tools, bundles, EDA artifacts, or GitHub issues. Prefix: context-teleport import.

All import commands support --dry-run to preview what would be imported.

Adapter Import¶

context-teleport import claude-code [--dry-run]
context-teleport import opencode [--dry-run]
context-teleport import codex [--dry-run]
context-teleport import gemini [--dry-run]
context-teleport import cursor [--dry-run]

Each adapter imports tool-specific files into the context store:

Tool	Sources
`claude-code`	`MEMORY.md`, `CLAUDE.md`, `.claude/skills/*/SKILL.md`
`opencode`	`AGENTS.md`, JSON sessions, `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/*/SKILL.md`
`codex`	`AGENTS.md`, `.codex/instructions.md`, `.codex/skills/*/SKILL.md`
`gemini`	`.gemini/rules/.md`, `STYLEGUIDE.md`, `GEMINI.md`, `.gemini/skills//SKILL.md`
`cursor`	`.cursor/rules/.mdc`, `.cursorrules`, `.cursor/skills//SKILL.md`

Conventions Import¶

context-teleport import conventions <file> [--dry-run] [--scope SCOPE]

Argument / Option	Short	Description
`file`		Path to a markdown file containing conventions
`--dry-run`		Preview what would be imported
`--scope`	`-s`	Scope for all imported conventions (default: `public`)

The file is split into individual conventions by markdown headers:

Try ## headers -- each becomes a convention with the slugified header as the key
If no ## headers, try # headers (skipping the first if it looks like a title)
If no headers at all, store as a single conventions entry

Bundle Import¶

context-teleport import bundle <path>

Import a portable .ctxbundle archive.

EDA Import¶

context-teleport import eda <path> [--type TYPE] [--dry-run]

Option	Short	Description
`--type`	`-t`	Force importer type. Auto-detected if omitted.
`--dry-run`		Preview what would be imported

Available importer types: librelane-config, librelane-metrics, magic-drc, netgen-lvs, orfs-config, liberty.

Artifact Import (Generic)¶

context-teleport import artifacts <path> [--type TYPE] [--list] [--dry-run]

Option	Short	Description
`--list`		Show all registered importers (built-in + plugins)
`--type`	`-t`	Force importer type
`--dry-run`		Preview what would be imported

Uses the plugin registry which includes built-in EDA parsers and any third-party importers installed via the ctx.importers entry-point group. See Adding Domain Importers for details on writing plugins.

# List all available importers
context-teleport import artifacts --list

# Auto-detect and import
context-teleport import artifacts /path/to/config.json

# Force a specific importer
context-teleport import artifacts /path/to/file --type liberty

GitHub Import¶

context-teleport import github [OPTIONS]

Option	Short	Default	Description
`--repo`	`-r`	auto-detect	GitHub repository (`owner/repo`)
`--issue`	`-i`		Import a single issue by number
`--labels`	`-l`		Comma-separated label filter
`--state`	`-s`	`all`	Issue state: `open`, `closed`, `all`
`--since`			Only issues after this date (ISO format, e.g. `2025-01-01`)
`--limit`	`-n`	`50`	Maximum issues to fetch
`--as-decisions`		`false`	Also create decision records for closed issues
`--dry-run`		`false`	Preview what would be imported

Tip

Requires gh CLI to be installed and authenticated. Repository is auto-detected from git remote -v when --repo is omitted.

export¶

Export context to external tool locations or bundles. Prefix: context-teleport export.

All export commands support --dry-run to preview what would be exported.

Adapter Export¶

context-teleport export claude-code [--dry-run]
context-teleport export opencode [--dry-run]
context-teleport export codex [--dry-run]
context-teleport export gemini [--dry-run]
context-teleport export cursor [--dry-run]

Bundle Export¶

context-teleport export bundle <path>

Export the context store as a portable .ctxbundle archive.

config¶

Manage global configuration. Prefix: context-teleport config.

get¶

context-teleport config get <key>

set¶

context-teleport config set <key> <value>

list¶

context-teleport config list

Available configuration keys:

Key	Valid Values	Description
`default_strategy`	`ours`, `theirs`, `interactive`, `agent`	Default merge strategy for `pull`
`default_scope`	`public`, `private`, `ephemeral`	Default scope for new entries