# Context Platform CLI

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

## Installation

From the repo root (uv workspace):

```bash
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.
When `ctxme get` saves to a directory, it sanitizes item keys into safe filenames (no path
separators or `..`).

## Tests

```bash
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:**

```bash
ctxme --install-completion bash
```

**Zsh:**

```bash
ctxme --install-completion zsh
```

**Fish:**

```bash
ctxme --install-completion fish
```

**PowerShell:**

```bash
ctxme --install-completion powershell
```

### Usage

```bash
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
