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.

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