CLI Tree¶

This page lists commands currently implemented and registered in chatcrs.cli. chatcrs --tree reads back signatures, while chatcrs --tree-brief keeps nodes and descriptions without signatures; both use the canonical chatcrs root. Command changes must keep this page aligned.

Top-level commands¶

chatcrs
├── --help  # Show this message and exit.
├── --version  # Show the version and exit.
├── --tree  # Print the registered CLI tree and exit.
├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
├── admin  # Remote CRS administrator operations via HTTPS Admin API.
│   ├── accounts  # Inspect or refresh remote CRS account state via HTTP Admin API.
│   │   ├── codex  # CRS 托管 Codex 账号；需原生 Admin 接口。
│   │   │   ├── consume [--profile PROFILE] [--account-id ACCOUNT-ID] [--timeout TIMEOUT] [--json-output] [--request-id REQUEST-ID] [--credit-id CREDIT-ID] [--execute]  # 默认本地计划；显式执行消费，不自动重放。
│   │   │   ├── credits [--profile PROFILE] [--account-id ACCOUNT-ID] [--timeout TIMEOUT] [--json-output]  # 只读查询重置卡，不消费。
│   │   │   ├── operation [--profile PROFILE] [--account-id ACCOUNT-ID] [--timeout TIMEOUT] [--json-output] [--request-id REQUEST-ID]  # 读取历史回执；待定或未知状态退出非零。
│   │   │   └── usage [--profile PROFILE] [--account-id ACCOUNT-ID] [--timeout TIMEOUT] [--json-output]  # 读取固定账号的实时上游额度；不是缓存统计。
│   │   ├── refresh-status [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--username USERNAME] [--password PASSWORD] [--admin-token ADMIN-TOKEN] [--timeout TIMEOUT] <ACCOUNT-ID> [--execute] [--json-output]  # Reset a CRS OpenAI account status after transient failures.
│   │   └── usage [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--username USERNAME] [--password PASSWORD] [--admin-token ADMIN-TOKEN] [--timeout TIMEOUT] [--json-output]  # List OpenAI/Codex account usage and scheduling metadata.
│   ├── keys  # Inspect remote CRS API keys with admin privileges.
│   │   ├── list [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--username USERNAME] [--password PASSWORD] [--admin-token ADMIN-TOKEN] [--timeout TIMEOUT] [--include-stats] [--time-range TIME-RANGE] [--json-output]  # List CRS API key metadata, optionally including usage stats.
│   │   └── show [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--username USERNAME] [--password PASSWORD] [--admin-token ADMIN-TOKEN] [--timeout TIMEOUT] <KEY-ID> [--include-stats] [--time-range TIME-RANGE] [--json-output]  # Show one CRS API key by id or name.
│   ├── login [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--username USERNAME] [--password PASSWORD] [--admin-token ADMIN-TOKEN] [--timeout TIMEOUT] [--save-token] [--json-output]  # Verify CRS admin login without printing the session token.
│   └── token  # Manage cached CRS admin session tokens in the ChatArch token store.
│       ├── clear [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--username USERNAME] [--password PASSWORD] [--admin-token ADMIN-TOKEN] [--timeout TIMEOUT] [--execute] [--json-output]  # Clear the cached CRS admin session token.
│       ├── refresh [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--username USERNAME] [--password PASSWORD] [--admin-token ADMIN-TOKEN] [--timeout TIMEOUT] [--json-output]  # Login and save a fresh CRS admin session token.
│       └── status [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--username USERNAME] [--password PASSWORD] [--admin-token ADMIN-TOKEN] [--timeout TIMEOUT] [--json-output]  # Show cached CRS admin token metadata without printing the token.
├── codex  # Direct OpenAI Codex account token and usage helpers.
│   ├── account [--profile PROFILE] [--access-token ACCESS-TOKEN] [--refresh] [--client-id CLIENT-ID] [--timeout TIMEOUT] [--json-output]  # Read a safe OpenAI Codex account summary from token claims and API probe.
│   ├── quota [--profile PROFILE] [--account-id ACCOUNT-ID] [--access-token ACCESS-TOKEN] [--refresh] [--client-id CLIENT-ID] [--model MODEL] [--timeout TIMEOUT] [--json-output]  # Run a profile-only Codex responses smoke and show quota headers.
│   ├── reset  # Inspect or explicitly redeem banked Codex resets without model requests.
│   │   ├── consume [--json-output] [--timeout TIMEOUT] [--base-url BASE-URL] [--profile PROFILE] [--request-id REQUEST-ID] [--execute]  # Plan or redeem one reset with a persisted receipt and GET readback.
│   │   └── list [--json-output] [--timeout TIMEOUT] [--base-url BASE-URL] [--profile PROFILE]  # Read reset count and expirations; renew profile credentials when required.
│   ├── token  # Manage OpenAI OAuth tokens through the ChatEnv Codex token store.
│   │   ├── refresh [--profile PROFILE] [--refresh-token REFRESH-TOKEN] [--client-id CLIENT-ID] [--timeout TIMEOUT] [--json-output]  # Refresh an OpenAI OAuth access token without printing token values.
│   │   └── status [--profile PROFILE] [--json-output]  # Show cached OpenAI OAuth token metadata without printing tokens.
│   └── usage [--profile PROFILE] [--account-id ACCOUNT-ID] [--access-token ACCESS-TOKEN] [--refresh] [--client-id CLIENT-ID] [--timeout TIMEOUT] [--json-output]  # Read Codex usage and quota metadata directly from OpenAI.
├── health [--base-url BASE-URL] [--json-output]  # Verify the CRS /health endpoint.
├── key  # CRS API-key-only operations that do not require admin login.
│   └── info [--profile PROFILE] [--base-url BASE-URL] [--api-key API-KEY] [--timeout TIMEOUT] [--path INFO-PATH] [--json-output]  # Query CRS key-info using only a CRS API key.
└── service  # Local CRS service lifecycle commands for the current server.
    ├── install [--app-dir APP-DIR] [--crs-command CRS-COMMAND] [--timeout TIMEOUT] [--execute] [--json-output]  # Plan or execute local `crs install` on this server.
    ├── restart [--app-dir APP-DIR] [--crs-command CRS-COMMAND] [--timeout TIMEOUT] [--execute] [--json-output]  # Plan or execute local `crs restart` on this server.
    ├── start [--app-dir APP-DIR] [--crs-command CRS-COMMAND] [--timeout TIMEOUT] [--execute] [--json-output]  # Plan or execute local `crs start` on this server.
    ├── status [--app-dir APP-DIR] [--crs-command CRS-COMMAND] [--timeout TIMEOUT] [--json-output]  # Execute local `crs status` on this server.
    ├── stop [--app-dir APP-DIR] [--crs-command CRS-COMMAND] [--timeout TIMEOUT] [--execute] [--json-output]  # Plan or execute local `crs stop` on this server.
    ├── switch-branch <BRANCH> [--app-dir APP-DIR] [--crs-command CRS-COMMAND] [--timeout TIMEOUT] [--execute] [--json-output]  # Plan or execute local `crs switch-branch <branch>` on this server.
    ├── update [--app-dir APP-DIR] [--crs-command CRS-COMMAND] [--timeout TIMEOUT] [--execute] [--json-output]  # Plan or execute local `crs update` on this server.
    └── update-pricing [--app-dir APP-DIR] [--crs-command CRS-COMMAND] [--timeout TIMEOUT] [--execute] [--json-output]  # Plan or execute local `crs update-pricing` on this server.

Coverage matrix¶

Capability	Implemented commands	Boundary
CRS health	`chatcrs health`	Read-only HTTP health summary
Admin login	`chatcrs admin login`	Verifies credentials; reports token presence only; `--save-token` writes the runtime token store
Admin token cache	`chatcrs admin token status`, `chatcrs admin token refresh`, `chatcrs admin token clear`	Manages short-lived Admin session tokens under `~/.chatarch/tokens/CRS/<profile>.json`; `chatcrs admin token refresh` is the ChatCRS-native command, and installed ChatCRS also registers the same provider for `chatenv token refresh CRS <profile>`; status output never prints tokens
Account usage	`chatcrs admin accounts usage`	Admin HTTP API; redacted usage/status/scheduling summary
Account status reset	`chatcrs admin accounts refresh-status`	Dry-run by default; `--execute` calls CRS reset-status; not an OAuth refresh-token force-refresh
API key statistics	`chatcrs admin keys list`, `chatcrs admin keys show`	Redacted key values, status, limits, stats, and last-usage summaries
API-key-only self info	`chatcrs key info`	No administrator login required
OpenAI/Codex direct token/account/usage	`chatcrs codex token ...`, `chatcrs codex account`, `chatcrs codex quota`, `chatcrs codex usage`	Calls OpenAI/Codex OAuth and backend APIs directly; output is limited to redacted token status, account summaries, and usage/quota header summaries
Local service lifecycle	`chatcrs service ...`	Runs local `crs` commands only on the CRS server; outside-server management must use HTTP/Admin API or a new service-side API/agent

Registered command list¶

Command	Responsibility
`chatcrs health`	CRS health check
`chatcrs admin login`	Admin login verification
`chatcrs admin token status`	Cached Admin session token metadata
`chatcrs admin token refresh`	Login and save a fresh Admin session token
`chatcrs admin token clear`	Dry-run or delete cached Admin session token
`chatcrs admin accounts usage`	Account usage inspection
`chatcrs admin accounts refresh-status`	CRS account reset-status
`chatcrs admin keys list`	API key list and statistics
`chatcrs admin keys show`	Single API key summary
`chatcrs key info`	API-key-only self check
`chatcrs codex token status`	Cached OpenAI OAuth token metadata
`chatcrs codex token refresh`	Refresh an OpenAI access token; prefer `chatenv token refresh Codex <profile>`
`chatcrs codex account`	Safe OpenAI Codex account summary from token claims/API probe
`chatcrs codex quota`	Profile-only Codex responses quota smoke; returns quota headers and account-id hash
`chatcrs codex usage`	Direct Codex usage inspection via usage endpoint
`chatcrs service install`	Local CRS install command plan/execute
`chatcrs service update`	Local CRS update command plan/execute
`chatcrs service start`	Local CRS start command plan/execute
`chatcrs service stop`	Local CRS stop command plan/execute
`chatcrs service restart`	Local CRS restart command plan/execute
`chatcrs service status`	Local CRS status command
`chatcrs service switch-branch`	Local CRS branch switch command plan/execute
`chatcrs service update-pricing`	Local CRS pricing update command plan/execute

Remote admin and API key¶

chatcrs admin login --profile admin --json-output
chatcrs admin login --profile admin --save-token --json-output
chatcrs admin token status --profile admin --json-output
chatcrs admin token refresh --profile admin --json-output
chatcrs admin token clear --profile admin --json-output
chatcrs admin token clear --profile admin --execute --json-output
chatcrs admin accounts usage --profile admin --json-output
chatcrs admin accounts refresh-status <account_id> --profile admin --json-output
chatcrs admin accounts refresh-status <account_id> --profile admin --execute --json-output
chatcrs admin keys list --profile admin --include-stats --json-output
chatcrs admin keys show <key_id_or_name> --profile admin --json-output

Meaning of refresh-status

refresh-status resets CRS account state. It does not force-refresh Codex/OpenAI OAuth refresh tokens.

API-key-only¶

chatcrs key info --profile admin --json-output
chatcrs key info --profile admin --path /openai/key-info --json-output

Codex direct¶

chatcrs codex token status --profile default --json-output
chatcrs codex token refresh --profile default --json-output
chatenv token refresh Codex default
chatcrs codex account --profile default --json-output
chatcrs codex quota --profile default --json-output
chatcrs codex usage --profile default --json-output

The codex branch calls OAuth and backend APIs through the selected Base URLs; a CRS caller key is not an account OAuth token. ChatCRS registers the Codex namespace with ChatEnv: stable configuration lives in envs/Codex/<profile>.env, while dynamic access/refresh tokens and expiry metadata live in tokens/Codex/<profile>.json. Usage queries use GET /wham/usage and prefer the stored account mapping. quota is a real model smoke, so choose a model supported by that account explicitly. chatenv token refresh Codex <profile> is the standard durable renewal path, also used automatically by reset profile clients.

Codex profiles must explicitly configure the non-secret Base URLs needed by each operation: OPENAI_OAUTH_BASE_URL for authentication and CHATGPT_BACKEND_BASE_URL for backend requests, usually including /backend-api. Missing configuration fails before a network request instead of falling back to an official host. Authorization and ChatGPT-Account-ID remain client-supplied headers and must not enter Nginx configuration or logs.

Server-local service¶

chatcrs service ... is a server-local surface. It assumes the command is installed and executed inside the CRS server shell, operating on that machine's CRS checkout / Node runtime / crs executable.

chatcrs service status --app-dir /path/to/crs --json-output
chatcrs service update --app-dir /path/to/crs --json-output
chatcrs service update --app-dir /path/to/crs --execute --json-output
chatcrs service restart --app-dir /path/to/crs --execute --json-output

Rules:

status is read-only and runs local crs status by default.
install, update, start, stop, restart, switch-branch, and update-pricing print a plan by default; --execute is required for execution.
The target comes only from the current working directory or explicit --app-dir; --crs-command selects only a local executable.
If the operator is outside the server, ordinary management must use chatcrs admin ... / chatcrs key ... HTTP/Admin APIs. Lifecycle capabilities without HTTP endpoints should be added to CRS as an API/agent or run from the server itself.

Removed task-specific surfaces¶

These categories remain unregistered:

local verify / sidecar verify;
Images acceptance;
debug runtime;
Nginx plan-cutover;
formal cutover precheck;
fixed-topology inspect.

They belong to special acceptance, debug runtime, edge/cutover runbooks, or proxy-site tasks, not the current core ChatCRS management CLI.

Safety boundaries¶

The outside-server CRS management surface is HTTP/Admin API.
The service surface runs only on the CRS server itself and does not maintain another server.
Any production mutation still requires explicit --execute, target verification, rollback boundary, and redacted output.
Env profiles keep stable configuration; short-lived Admin session tokens are cached under ~/.chatarch/tokens/CRS/<profile>.json instead of frequently rewriting Env files.
API keys, tokens, passwords, and OAuth credentials must not appear in chat, docs, PR bodies, or command output.

Banked Codex resets¶

Profile clients use the registered ChatEnv Codex renewal flow: stable configuration stays in envs/Codex, while rotated access/refresh tokens and expiry metadata are written only to tokens/Codex, without changing ENV. Expired credentials are renewed before use. A read-only GET 401 permits one renewal/retry; a consume POST is never replayed. Rejected refresh credentials require renewed authorization, not another proxy or a copied token from a different service.

Configure the HTTPS Base URLs needed by the account operation. All ChatCRS HTTP transports ignore environment/system proxies and reject redirects. The repository provides infra/nginx/codex-relay.conf.example; the reverse proxy forwards requests without storing account secrets.

OPENAI_OAUTH_BASE_URL=https://auth-relay.example.com
CHATGPT_BACKEND_BASE_URL=https://gpt-relay.example.com/backend-api

Python consumers use CodexResetClient.from_profile("work", refresh=True). Set refresh=False explicitly for diagnostics that must not renew credentials. OAuth belongs in ChatCRS, not dashboard code or machine-private scripts.

chatcrs codex reset list reads available count and expirations with GET /wham/rate-limit-reset-credits, without model generation; credentials are renewed through ChatEnv when required, updating only the runtime token store. chatcrs codex reset consume is a dry-run unless both a persistent --request-id and --execute are provided. It persists an audit before sending and performs GET readback afterward. The same request ID is never sent twice; resolve uncertain outcomes through read-only inspection instead of creating another ID. A full reset changes the natural reset schedule and is not a Credits purchase.

chatcrs codex reset list --profile work --json-output
chatcrs codex reset consume --profile work --request-id one-reviewed-operation --json-output

An explicit --base-url can select a reset backend when a configured relay does not expose reset routes; it does not change the profile usage/auth base or stored config. These are evolving ChatGPT backend endpoints, not a stable public OpenAI Platform API. Python consumers use chatcrs.reset_credits.CodexResetClient, inspect_reset_credits, and consume_reset_credit. Client consume(..., execute=True) requires caller-owned policy and durable de-duplication; ChatGlance threshold policy stays outside ChatCRS.

CRS-managed Codex (0.3.5)¶

This managed client is introduced in 0.3.5, and is not included in 0.3.4. Network operations require the native CRS routes below, authenticated by a scoped management Key or an existing Admin session. Older servers without these routes fail closed: no local OAuth, cached-statistics or reset-status fallback. Installing the client does not upgrade the CRS server.

Every command requires --account-id. --profile defaults to default and selects the existing CRS ChatEnv namespace, never a Codex OAuth profile. It pins the server origin/account identity (token_service="CRS") without copying upstream OAuth credentials. Dashboards should use a dedicated management Key (CRS_API_KEY, crsm_ prefix) in the selected CRS profile: Key mode never reads an Admin session or falls back to username/password login, including after rejection. Without a Key, operator calls use an already-established CRS Admin session only; missing or rejected sessions fail without login, renewal or replay. Establish a session separately with chatcrs admin login --profile <profile> --save-token. Legacy Admin commands keep their normal login lifecycle; ordinary model Keys are not accepted. The thin CLI lazily calls chatcrs.managed_codex.CrsManagedCodexClient.from_profile(crs_profile="default", account_id="account-placeholder", home=None, timeout=20). Python consumers use its identity, token_service, and methods directly, without shelling out to the CLI.

CLI	Native CRS route (server prerequisite)	Python method / mutation boundary
`chatcrs admin accounts codex usage`	`GET /admin/openai-accounts/{account_id}/codex/usage`	`usage()`; fresh upstream windows, read-only
`chatcrs admin accounts codex credits`	`GET /admin/openai-accounts/{account_id}/codex/reset-credits`	`reset_credits()`; read-only, never consumes
`chatcrs admin accounts codex consume`	`POST /admin/openai-accounts/{account_id}/codex/reset-credits/consume`	`consume(request_id, credit_id=None, execute=False)`; local network-free dry-run by default
`chatcrs admin accounts codex operation`	`GET /admin/openai-accounts/{account_id}/codex/reset-credits/operations/{request_id}`	`operation(request_id)`; read-only historical receipt

chatcrs admin accounts codex usage --profile crs-profile --account-id account-placeholder --json-output
chatcrs admin accounts codex credits --profile crs-profile --account-id account-placeholder --json-output
chatcrs admin accounts codex consume --profile crs-profile --account-id account-placeholder --request-id request-placeholder --json-output
chatcrs admin accounts codex operation --profile crs-profile --account-id account-placeholder --request-id request-placeholder --json-output

consume and operation require --request-id; consumption optionally accepts --credit-id credit-placeholder. Add --execute only after reviewing the target and persist the same request ID. Each CLI invocation calls the adapter method once: no automatic replay or new ID. Inspect an uncertain receipt with the original ID instead of blindly consuming again.

--json-output emits the adapter's safe structured JSON. Exceptions produce fixed safe errors and nonzero exits, never raw exceptions or credentials. A local dry_run exits 0. Executed consumption and historical receipts exit 0 only for reset_verified, nothing_to_reset, or no_credit (the latter two do not mean a credit was consumed). uncertain, pending, unknown states, HTTP 202, and exceptions are not success and exit nonzero. Historical unknown receipt states may be displayed but are not fresh quota verification. Existing chatcrs admin accounts usage keeps its cached CRS statistics semantics.