CLI Reference

Installation

Install the CTX Me CLI from PyPI. Requires Python 3.10+.

pip install ctxme

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

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 <shell> — Install shell completion (see Shell Completion)

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> — 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.

Commands

Authentication

  • ctx auth login — Device flow sign-in (opens browser, stores API key in keychain; --scopes read,write,admin requests specific key scopes, default read,write)
  • 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 to filter, --all for all projects)
  • ctx get <item> — Download an item to the current directory (--stdout/--clipboard for text items)
  • ctx read <item> — Retrieve item text content for AI consumption (--stdout prints content only; --max-chars limits length)
  • ctx create <item> --data "<text>" — Create or update an inline item (--title, --tag optional)
  • ctx create <item> --src <path> — Upload a file as a context item
  • ctx upload <path> — Upload a file as an item (equivalent to create --src)
  • ctx update <item> — Update item metadata: title, MIME type, folder, and tags
  • ctx delete <item> — Delete an item (--force to skip confirmation)
  • ctx folders — List folder paths and item counts
  • ctx mv <item> --folder <path> — Move an item to a folder (empty string "" moves it to the root)

ls and put are hidden backwards-compatibility aliases of list and create; prefer the canonical names.

  • ctx search <query> — Search for items across projects (--tag to filter by tag)

Projects

  • ctx projects list — List available projects
  • ctx projects current — Show the current default project
  • ctx projects create <name> — Create a new project (--key for an explicit project key)
  • ctx projects delete <key> — Delete a project
  • ctx set-project <project> — Set the default project key

LLM Usage

  • ctx usage llm — List recent LLM invocations for your account (requires an admin-scoped key; filters: --project, --since, --until, --status, --workload, --model)

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
  • ctx wiki get <slug> — Show a wiki page's content and metadata
  • ctx wiki search <query> — Search wiki pages
  • ctx wiki query "<question>" — Ask the wiki for a synthesized, cited answer (--file-back files novel answers as new wiki pages)
  • ctx wiki settings — Show or change wiki settings (external LLM opt-in)
  • ctx wiki runs — Show wiki maintenance run history
  • ctx wiki schema get — Print the wiki schema page body
  • ctx wiki schema set [file] — Replace the wiki schema from a file or 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 (.txt, .md, .pdf, .docx, .csv, .tsv, .html)
# 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_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 (process env only; takes precedence over keychain)
  • 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 flags.

Bash:

ctx --install-completion bash

Zsh:

ctx --install-completion zsh

Fish:

ctx --install-completion fish

PowerShell:

ctx --install-completion powershell

Usage

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