> ## Documentation Index
> Fetch the complete documentation index at: https://costhq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CostHQ CLI Reference: All cs Commands and Global Flags

> Complete command list for the CostHQ cs CLI. All commands support --json for machine-readable output and exit code 0 on success, 1 on error.

The `cs` CLI is the main interface to CostHQ. Installing the `costhq` package globally gives you two binaries — `costhq` and `cs` — that point to the same interface. Every command in this reference works identically with either binary.

## All Commands

| Command                                             | Description                                   |                 |
| --------------------------------------------------- | --------------------------------------------- | --------------- |
| `cs start <name>`                                   | Start tracking a session                      |                 |
| `cs start --resume`                                 | Resume existing session for current directory |                 |
| `cs start --close-stale`                            | Auto-close orphaned sessions, then start      |                 |
| `cs end [-n notes] [-s id]`                         | End session                                   |                 |
| `cs status [-s id]`                                 | Show active session                           |                 |
| `cs show [id] [--files] [--commits]`                | Show session details                          |                 |
| `cs list [-l limit]`                                | List recent sessions                          |                 |
| `cs stats`                                          | Overall statistics                            |                 |
| `cs log-ai -p <provider> -m <model> [opts]`         | Log AI usage                                  |                 |
| `cs note <message> [-s id]`                         | Add annotation                                |                 |
| `cs recover [--max-age hours]`                      | Auto-end stale sessions                       |                 |
| \`cs export \[--format json                         | csv] \[--limit n]\`                           | Export sessions |
| `cs dashboard [--port] [--host] [--no-open]`        | Open web analytics dashboard                  |                 |
| `cs pricing list`                                   | Show model prices                             |                 |
| `cs pricing set <model> <in> <out> [--provider]`    | Set custom pricing per 1M tokens              |                 |
| `cs pricing reset`                                  | Remove custom price overrides                 |                 |
| `cs run [--name] [--port] [--no-proxy] <command>`   | Wrap a command with full session lifecycle    |                 |
| `cs proxy [--port] [-s/--session <name>]`           | Start local API proxy                         |                 |
| `cs budget [--daily <amount>] [--session <amount>]` | Configure spend alerts                        |                 |

\| `cs auto-log [--provider] [--model] [--agent]` | Auto-log from Claude Code transcript |
\| `cs local-models add <provider>/<model>` | Register a local model and its compute cost |
\| `cs local-models list` | List all registered local models |
\| `cs team set --name <team> --member <name>` | Set team identity for audit logs (Enterprise) |
\| `cs audit log` | View the tamper-evident audit trail (Enterprise) |
\| `cs audit verify` | Verify the cryptographic integrity of the audit log (Enterprise) |

## Global Flags

| Flag     | Behavior                                                       |
| -------- | -------------------------------------------------------------- |
| `--json` | Return machine-readable JSON instead of formatted table output |

All `--json` responses include two metadata fields at the top level:

* **`schemaVersion`** — currently `1`. Check this field before parsing; if it is higher than expected, degrade gracefully rather than silently breaking.
* **`CostHQVersion`** — the installed version string (e.g. `"3.1.1"`).

Exit codes are unambiguous: `0` on success, `1` on any error — including in `--json` mode.

## Session Scoping

CostHQ scopes sessions by **git root**, not by the exact directory from which you ran `cs start`. If you run `cs start` from `repo/apps/web`, the session's working directory resolves to the repository root (e.g. `repo/`). This prevents accidental session fragmentation when agents or humans invoke commands from different subdirectories of the same repository.

If you are not inside a git repository, CostHQ uses the exact current working directory as-is. The resolved scope is visible in the `gitRoot` field of `cs status --json`.

<Tip>
  Use `cs start --close-stale` in automation scripts to avoid `session_active` errors caused by crashed agents that left an open session behind.
</Tip>