ctxme 0.1.4

Context Platform CLI

Context Platform CLI

Typer-powered command-line interface for managing Context Platform projects and items.

Installation

From the repo root (uv workspace):

uv sync --all-extras --all-groups

ctxme will then be available via uv run ctxme ... (or activate .venv and call directly).

Configuration

The CLI stores settings under the platform-specific config directory (see platformdirs). Override the path in scripts/tests with the CTXME_CONFIG_DIR environment variable.

Key commands:

• ctxme config --api <url> – set the backend API base URL (switches to live mode)
• ctxme config --mode mock|live – toggle between the built-in mock client and HTTP client
• ctxme set-project <project> – set the default project key
• ctxme auth login – device flow sign-in (opens browser, stores API key in keychain)
• ctxme auth status – show stored API key prefix + backend metadata
• ctxme auth set-key <key> – manually persist API keys using the OS keychain
• ctxme auth logout – remove stored API key

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

Commands

• ctxme ls – list items for the default (set-project) or --project project
• ctxme get <item> – download an item to the current directory (use --stdout to print)
• ctxme put <item> --data "<text>" – create or update an item (--title, --tag optional)
• ctxme remove <item> – delete an item (use --force to skip confirmation)
• ctxme projects list / ctxme projects ls – list available projects
• ctxme projects current – show the current default project (local only)
• ctxme set-project <project> – set the default project key
• ctxme status – show local config + auth status (no API call)

All commands emit Rich-formatted tables/panels with user-friendly messaging.

Environment Variables

Variable	Description
CTXME_DEBUG	Set to 1 to enable debug output (shows API URL, mode, and full tracebacks on errors)
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__DEFAULT_PROJECT	Override the default project (takes precedence over config file)
CLI__USE_MOCK_CLIENT	Set to true to use the mock client

Example: View full configuration details

CTXME_DEBUG=1 ctxme status
# Output:
# API: https://api.example.com
# Mode: live
# Auth: Signed in
# Project: my-project (default)

When ctxme get saves to a directory, it sanitizes item keys into safe filenames (no path separators or ..).

Tests

uv run pytest cli/tests

Tests cover configuration round-trips, keyring helpers (via an in-memory backend), and representative Typer command flows.

Shell Completion

Enable tab completion for commands, subcommands, and flags.

Installation

Bash:

ctxme --install-completion bash

Zsh:

ctxme --install-completion zsh

Fish:

ctxme --install-completion fish

PowerShell:

ctxme --install-completion powershell

Usage

ctxme <TAB>        # Shows: auth, config, get, ls, put, ...
ctxme auth <TAB>   # Shows: login, logout, status, set-key
ctxme get --<TAB>  # Shows: --project, --dest, --stdout, --force, ...

Troubleshooting

• Restart shell after installation
• Ensure completion script is sourced in shell config
• Check ctxme --show-completion <shell> for manual setup