CLI Reference

Installation

Both ctx and ctxme commands are available after installation — they are identical. Examples below use ctx.

brew install ctxme/cli/ctxme

That one command adds the tap and installs the CLI. Upgrade later with brew upgrade ctxme.

Name the formula in full the first time. Homebrew requires formulae from third-party taps to be trusted before it will load them (HOMEBREW_REQUIRE_TAP_TRUST, on by default since Homebrew 6), and naming a formula explicitly grants that trust — after which plain brew install ctxme and brew upgrade ctxme work too.

Tapping first is equivalent, but takes an explicit trust step:

brew tap ctxme/cli
brew trust ctxme/cli
brew install ctxme

Without brew trust, the install fails with Refusing to load formula ctxme/cli/ctxme from untrusted tap ctxme/cli.

From PyPI

Requires Python 3.10+.

pip install ctxme        # or: pipx install ctxme

Global Options

  • ctx --version — Show the CLI version and exit
  • ctx --output json <command> (-o json) — Emit errors as a machine-parseable JSON envelope. Error output only; successful output stays in text format (see JSON Output)
  • ctx --install-completion — Install shell completion for the current shell (see Shell Completion)
  • ctx --show-completion — Print the completion script instead of installing it, to copy or customize

Configuration

The CLI stores settings under the platform-specific config directory. Override the path with the CTXME_CONFIG_DIR environment variable.

Key commands:

  • ctx config --default-project <project> (-p) — Set the default project key
  • ctx set-project <project> — Set the default project key (same effect)
  • ctx current — Show the current default project (local only)
  • ctx status — Show local config + auth status (no API call)

API keys are never written to disk; they are stored through the OS keyring only.

Command Conventions

Two options recur across the command set and are called out below only where their behaviour is unusual:

  • --project <key> (-p) targets a project other than the default. Most commands that read or write project data accept it.
  • --json switches a command's successful output to machine-parseable JSON. Most commands accept it; see JSON Output for how it differs from the global --output json.

Pagination. ctx list, ctx folders, ctx usage llm, ctx wiki list, and ctx wiki runs accept --cursor <token>, where the token comes from a previous response. Because that token is only returned in JSON output, --cursor requires --json. Each of these commands also takes --limit; ctx list additionally offers --no-limit to walk every page in one invocation.

Commands

Authentication

  • ctx auth login — Device flow sign-in (opens browser, stores API key in keychain). The key is issued at your own permission ceiling — admin for an admin-role user, write for a standard-role user — and the browser shows that exact permission before you authorize. Pass --scopes read,write,admin to request a specific list instead; requests above your role's ceiling are denied at verification. --no-open-browser prints the verification URL rather than opening a browser
  • ctx auth status — Show stored API key prefix + backend metadata
  • ctx auth set-key <key> — Manually persist an API key using the OS keychain
  • ctx auth logout — Remove stored API key

Managing Items

Item commands are available at the top level and, identically, under the ctx items group (ctx list ≡ ctx items list).

  • ctx list — List items for the default or --project project. --folder/-f filters by folder path and --recursive/-r includes subfolders (requires --folder); --all/-a lists across all projects; --limit/-l caps results (1-200, default 50), --no-limit returns everything by fetching all pages, and --cursor resumes from a previous response; --sort/-s and --order/-o control ordering (default updated_at, with date fields defaulting to descending and text fields to ascending)
  • ctx get <item> — Download an item to the current directory. --dest writes to a given file or directory, --force overwrites an existing destination, --stdout and --clipboard/-c print or copy text items instead of saving, and --text/-t returns extracted text for file items where available
  • ctx read <item> — Retrieve item text content for AI consumption (--stdout prints content only, --clipboard/-c copies it, --max-chars limits length)
  • ctx create <item> --data "<text>" — Create or update an inline item (--title, --tag/-t repeatable, --folder, --mime-type, --force to overwrite without prompting, --rename to save under a different key interactively)
  • ctx create <item> --src <path> — Upload a file as a context item (--key overrides the item key derived from the filename)
  • ctx upload <path> — Upload a file as an item (equivalent to create --src). --key/-k overrides the derived item key; --title, --tag/-t, --force, and --rename behave as they do for create
  • ctx update <item> — Update item metadata: --title, --mime-type, --folder, and tags. --tag/-t replaces every tag and is mutually exclusive with the incremental options --add-tag, --remove-tag, and --clear-tags
  • ctx delete <item> — Delete an item (--force to skip confirmation)
  • ctx folders — List folder paths and item counts (--parent lists only the direct children of a folder; --limit/-l and --cursor paginate)
  • ctx mv <item> --folder <path> — Move an item to a folder (empty string "" moves it to the root)

--mime-type applies to inline content only. For inline items (--data, or text entered at the prompt) ctx create --mime-type accepts plain, markdown, or json. On the file-upload paths it is ignored: both ctx create --src and ctx upload derive the MIME type from the file extension and print a note when a --mime-type is supplied anyway. ctx update --mime-type is unaffected — it sets the stored MIME type of an existing item.

Hidden backwards-compatibility aliases do not appear in --help; prefer the canonical names:

  • Top level: ctx ls (list), ctx rm (delete), ctx put (create), ctx up (upload), and ctx use (set-project)
  • Under ctx items: ctx items ls, ctx items rm, and ctx items put. There is no ctx items up — up is registered on the top level only
  • Elsewhere: ctx projects ls (projects list) and ctx wiki ls (wiki list)
  • ctx search <query> — Search for items (see Search Modes). --tag/-t filters by tag (repeatable, AND semantics), --all/-a searches every project, --limit/-l caps results and applies only with --all, and --include-pending includes items still processing or failed

Projects

  • ctx projects list — List available projects
  • ctx projects current — Show the current default project (local only)
  • ctx projects create <name> — Create a new project (--key/-k for an explicit project key, --description/-d for a description)
  • ctx projects delete <key> — Delete a project (--yes/-y skips the confirmation prompt when deleting the default project)
  • ctx set-project <project> — Set the default project key

Skills

The ctx skills group publishes skill bundles to your account catalog and installs them for Claude Code and Codex on this computer.

Producing and publishing a bundle

  • ctx skills validate <path> — Validate a local skill directory, reporting every finding plus the name and targets declared by SKILL.md. Warnings exit 0; errors exit non-zero. It reads no credentials and contacts no backend
  • ctx skills pack <path> — Validate, then build a reproducible ZIP. The default output is <source-parent>/<skill-name>.zip — the source directory's own name has no catalog meaning. --archive <file> chooses another path and --overwrite replaces an existing archive; the output may not sit inside the source tree
  • ctx skills publish <path> — Build the same ZIP in memory and publish it to your account catalog. The ordered plan is always printed before anything changes: interactive runs prompt once, and --yes is required in non-interactive or JSON mode. An identical published version is a no-op and an identical draft is reused; a different existing draft refuses unless you pass --replace-draft, which --yes never implies. --dry-run shows the plan, performs only the catalog read, and writes nothing

Create, upload, and publish are separate server steps rather than one transaction, so a failure part-way can leave an empty catalog record or an uploaded draft behind. The command's output names whatever state remains.

Installing skills

ctx skills sync <name>[@<version>]... installs named skills from your account catalog. A version defaults to @latest; @<number> pins one.

Choose a destination one of two ways:

  • --agent claude|codex|both together with --scope user|directory. user (the default scope) installs into ~/.claude/skills or ~/.agents/skills; directory installs into <path>/.claude/skills or <path>/.agents/skills and requires --path <dir>. --agent is required for both scopes, and both installs one unit per agent
  • --dest <dir> for a custom destination (<dir>/<name>), mutually exclusive with --agent, --scope, and --path. --variant standard|claude selects the installed variant (default standard) and is only valid with --dest

The remaining options are the decisions that matter:

  • --mode symlink|copy — Install mode, defaulting to symlink everywhere except Windows, where it is copy. A symlink install points at an immutable managed store under the data directory, so the installed tree is never edited in place
  • --on-conflict overwrite|backup — The explicit conflict-resolution action for a destination holding unmanaged or drifted content. Without it, a conflicting install refuses. overwrite moves the existing entry aside and restores it if the install fails; backup retains it at a timestamped <name>.bak-<timestamp> sibling. Neither --yes nor the interactive prompt ever authorizes an overwrite
  • --yes — Skip the confirmation. Required in non-interactive or JSON mode: an install is never implied by the output format
  • --dry-run — Print the install plan and change nothing. It needs no --yes

Every install is verified against the catalog's published bundle and previews publisher, version, files, destination, mode, and conflicts before touching anything. An install that fails leaves the destination as it found it.

Run ctx skills sync with no names to apply this machine's profile instead — see "This computer's machine profile" below.

Managing installed skills

  • ctx skills list [<name>...] — Show the locally managed installs, never the account catalog: skill, installed version, variant, agent, scope, destination, mode, publisher, hold marker, and a drift status computed from the destination (ok, drifted, missing, or store-missing). Narrow with --agent, --scope, --path, or --dest. Read-only and offline, unless --outdated is passed, which additionally resolves each record's latest catalog version
  • ctx skills update [<name>[@<version>]...] | --all — Update managed installs. Bare <name> or @latest tracks the newest version and clears any hold; @<number> pins a version (downgrades included) and holds the record there. Each record keeps its recorded agent, scope, destination, mode, and variant — changing those stays sync's job. Named invocations are all-or-refuse, while --all reports and continues per record. Accepts the same --agent/--scope/--path/--dest filters plus --yes and --dry-run
  • ctx skills rollback <name>[@<version>] — Roll an install back to an earlier version and hold it there. Bare <name> returns to the newest superseded version in that destination's history; @<number> targets any version. Same filters, --yes, and --dry-run
  • ctx skills prune [<name>...] | --all — The only surface that removes an installed skill. It removes the destination entry and its managed record, locally, without contacting the server; content the CLI does not manage is invisible to it under every flag combination. A drifted install refuses unless you pass --backup, which preserves the observed entry at a timestamped .bak-* sibling first. Accepts the same --agent/--scope/--path/--dest filters, plus --yes and --dry-run
  • ctx skills gc — Free space in the managed store only. It never touches an installed destination — removal is prune's job alone. It drops superseded versions past the retained depth and then collects store data no install still references. --keep <n> sets that depth for the invocation; --keep 0 drops every superseded version, after which a later rollback re-downloads. --dry-run reports every tier without deleting

Consent. These operations ask before they act: skills publish, skills sync, skills update, skills rollback, skills prune, skills machine register --adopt, and skills machine unregister. Each of them requires --yes whenever the run is non-interactive or uses --json, and refuses without it — consent is never implied by the output format. A --dry-run never needs it, since it changes nothing, and publish reaches its consent check only once the plan it printed would actually mutate the catalog. The machine commands have no dry run, so there --yes is the only non-interactive route.

This computer's machine profile

A machine's profile is the selection set you save for it in the web UI; there is no separate profile entity. Server-side selections never carry absolute paths, so a directory or custom-destination selection carries a path-independent destination key that this computer maps locally.

  • ctx skills machine register — Bind this computer to a machine record. --name sets the display name (default: this host's name) and the platform is detected automatically. If a machine of that name already exists in the account, register refuses and names --adopt. --adopt binds to that existing record after a confirmation warning that this computer will apply that machine's selections and that two computers sharing one record contend for a single selection set. --yes skips that confirmation and is required to adopt non-interactively or with --json
  • ctx skills machine status — Show this computer's registration: the local identity, mapping count and — when a credential is available and the origin matches — the live machine detail and selection count. A missing credential, an unreachable backend, or a deleted machine record degrades to local-only output with a warning rather than failing
  • ctx skills machine unregister — Forget the local binding only (--yes skips the confirmation, and is required to run it non-interactively or with --json). Mappings are retained, nothing is uninstalled, and the server-side machine record and its selections are untouched

A bare ctx skills sync applies the registered machine's profile. In that form only --yes, --dry-run, and --json are accepted — every other sync option is a usage error, because each selection carries its own agent, scope, destination key, variant, and mode. It refuses before touching anything if this computer is not registered, was registered against a different backend, or has had its machine record deleted server-side; an empty profile reports nothing to install and exits 0.

Application is per selection, report-and-continue: a selection that cannot be applied is refused with its reason and the exact remediation — a ctx skills mapping set for an unmapped destination key, or the precise named ctx skills sync ... --on-conflict ... re-invocation for a drifted or unmanaged destination — and the remaining selections still apply. The run exits non-zero whenever any selection refused or failed, --dry-run included, so a preview never reports a broken profile as healthy. A record held by ctx skills update <name>@<n> or ctx skills rollback is skipped rather than changed.

Applying a profile never removes anything: managed installs outside the profile, installs deselected since the last sync, and unmanaged content are all left alone. Removal remains ctx skills prune's alone.

Destination-key mapping

  • ctx skills mapping set <key> <path> — Map a destination key to an absolute path on this computer. A key is 1-64 characters of lowercase letters, digits, ., _, or -, starts with a letter or digit, and never contains ... The path is ~-expanded, must be absolute, and is stored canonically, so two spellings of one directory are recognised as one destination. A path that does not exist yet is stored with a warning, and re-pointing a key warns that content installed under the old path is neither moved nor removed
  • ctx skills mapping list — List this computer's destination-key mappings
  • ctx skills mapping remove <key> — Remove a mapping. It uninstalls nothing

Mapping commands need neither registration nor authentication.

For the full detail behind these commands — transaction semantics, the managed store layout, and per-flag reference — see the CLI README.

LLM Usage

  • ctx usage llm — List recent LLM invocations for your account (requires an admin-scoped key). Filters: --project, --since/--until (ISO-8601), --status, --workload, --model. --limit/-l caps results (1-100, default 50) and --cursor paginates

Wiki

  • ctx wiki status — Show wiki generation state, staleness, and coverage
  • ctx wiki generate — Trigger wiki generation or refresh
  • ctx wiki list — List wiki pages (--page-type, --include-stale, --limit/-l, --cursor)
  • ctx wiki get <slug> — Show a wiki page's content and metadata
  • ctx wiki search <query> — Search wiki pages (--page-type, --include-stale, --limit/-l)
  • ctx wiki query "<question>" — Ask the wiki for a synthesized, cited answer (--limit/-l caps the pages retrieved). --file-back files novel answers as new wiki pages — filed pages are visible to the whole account
  • ctx wiki settings — Show or change wiki settings; --llm-opt-in / --no-llm-opt-in enables or disables external LLM processing for this project's wiki
  • ctx wiki runs — Show wiki maintenance run history (--status, --trigger, --limit/-l, --cursor)
  • ctx wiki schema get — Print the wiki schema page body
  • ctx wiki schema set [file] — Replace the wiki schema from a file or stdin (omit the file, or pass -, to read stdin)

Maintenance

  • ctx update-check — Check for newer versions of the CLI

JSON Output

Two distinct mechanisms — they are independent and do not imply each other:

  • Per-command --json — Switches a command's successful output to machine-parseable JSON (e.g. ctx list --json, ctx read <item> --json --stdout). Supported by most commands.
  • Global --output json (-o json) — Switches error output to a machine-parseable JSON envelope. It does not change successful command output; combine it with per-command --json when scripting.

Search Modes

The search command determines which projects to search based on your configuration:

Explicit project search (using --project):

ctx search "machine learning" --project my-research

Default project search (when default project is set):

ctx set-project my-main-project
ctx search "API documentation"

All-projects search (using --all or when no default is set):

ctx search "kubernetes config" --all --limit 20

The --project and --all flags are mutually exclusive.

Unified Context Items

The CLI uses a unified API that handles both inline text and file uploads:

  • Inline content: Use --data to provide text content directly
  • File uploads: Use --src or ctx upload to upload supported files (.csv, .docx, .htm, .html, .json, .markdown, .md, .pdf, .tsv, .txt)
# Create inline item
ctx create my-notes --data "Meeting notes from today"

# Upload a file
ctx create quarterly-report --src ./report.docx

# List items with processing status
ctx list

When uploading files, extraction and indexing happen asynchronously. Use ctx list to check when the status changes to ready.

Environment Variables

  • CTXME_DEBUG — Set to 1 to enable debug output (API URL, mode, full tracebacks)
  • CTXME_CONFIG_DIR — Override the default config directory path
  • CTXME_CACHE_DIR — Override the default cache directory path
  • CTXME_DATA_DIR — Override the default data directory path. The managed skills store lives inside it, at <CTXME_DATA_DIR>/skills-store
  • CTXME_UPDATE_CHECK — Set to 0, false, or no to disable automatic update checks at startup
  • CTXME_UPDATE_CHECK_INTERVAL — Override the update check interval in seconds (default: 86400 / 24 hours)
  • CLI__API_BASE_URL — Override the backend API URL (takes precedence over config file)
  • CLI__API_KEY — Override the API key. It is read from the process environment only (never from .env files), takes precedence over the keychain, and is visible in process listings — use it for local testing rather than as a standing credential
  • CLI__DEFAULT_PROJECT — Override the default project (takes precedence over config file)
  • CLI__USE_MOCK_CLIENT — Set to true to use the mock client

Shell Completion

Enable tab completion for commands, subcommands, and options. The CLI detects the shell it is running in — bash, zsh, fish, and PowerShell are supported — so neither flag takes a shell argument.

ctx --install-completion

Completion takes effect once you restart the terminal.

To read or customize the script instead of installing it, print it and redirect it wherever your shell expects:

ctx --show-completion

Usage

ctx <TAB>          # Shows: auth, config, get, list, create, ...
ctx auth <TAB>     # Shows: login, logout, status, set-key
ctx skills <TAB>   # Shows: validate, pack, publish, sync, list, ...
ctx get --<TAB>    # Shows: --project, --dest, --stdout, --force, ...