CLI and HTTP Interface Map

This page aligns the current ChatCRS CLI surface with its execution boundary. Outside-server management commands map to the CRS HTTP/Admin API; service is a server-local surface that runs local crs commands only on the CRS server itself.

Current CLI tree

chatcrs
├── health                         # GET /health
├── admin                          # CRS Admin HTTP API command group
│   ├── login                      # POST /web/auth/login
│   ├── token                      # local runtime Admin session token cache
│   │   ├── status                 # token file metadata, no token output
│   │   ├── refresh                # POST /web/auth/login; ChatEnv writes token file for provider refresh
│   │   └── clear                  # dry-run/delete local token file
│   ├── accounts                   # OpenAI/Codex account state
│   │   ├── usage                  # GET /admin/openai-accounts
│   │   └── refresh-status         # POST /admin/openai-accounts/{account_id}/reset-status
│   └── keys                       # CRS API key metadata and statistics
│       ├── list                   # GET /admin/api-keys + batch stats/last usage
│       └── show                   # GET /admin/api-keys + batch stats/last usage, filtered by id/name
├── key                            # API-key-only self inspection
│   └── info                       # GET /openai/key-info
├── codex                          # Direct OpenAI Codex OAuth/backend helpers
│   ├── token
│   │   ├── status                 # local OpenAI token-store metadata, no token output
│   │   └── refresh                # POST OPENAI_OAUTH_BASE_URL/oauth/token
│   ├── account                    # GET OPENAI_OAUTH_BASE_URL/api/accounts
│   ├── quota                      # POST CHATGPT_BACKEND_BASE_URL/codex/responses
│   └── usage                      # GET CHATGPT_BACKEND_BASE_URL/wham/usage
└── service                        # server-local service lifecycle
    ├── install                    # local crs install; dry-run by default
    ├── update                     # local crs update; dry-run by default
    ├── start                      # local crs start; dry-run by default
    ├── stop                       # local crs stop; dry-run by default
    ├── restart                    # local crs restart; dry-run by default
    ├── status                     # local crs status; read-only execution by default
    ├── switch-branch              # local crs switch-branch; dry-run by default
    └── update-pricing             # local crs update-pricing; dry-run by default

CLI to HTTP / local interface

CLI	Interface	Authentication source	Mutation	Python API
chatcrs health	GET /health	None; configured base URL field or --base-url	No	health-check helper
chatcrs admin login	POST /web/auth/login	configured admin identity/password fields, or explicit options	No durable mutation by default; --save-token writes the runtime token file	CrsHttpClient.login
chatcrs admin token status	local token file read	CRS profile + runtime token store	No	CrsTokenStore.status
chatcrs admin token refresh	POST /web/auth/login; chatenv token refresh CRS <profile> uses the same provider and lets ChatEnv write the token file	Admin username/password from matching stable envs/CRS/<profile>.env profile	Writes ~/.chatarch/tokens/CRS/<profile>.json only through ChatEnv token-store persistence	chatcrs.tokens.refresh_chatenv_token / CrsHttpClient.login(save_token=True)
chatcrs admin token clear	local token file delete	CRS profile + runtime token store	Dry-run by default; deletes only with --execute	CrsTokenStore.clear
chatcrs admin accounts usage	GET /admin/openai-accounts	Admin bearer token, resolved from profile/login	No	CrsHttpClient.accounts_usage
chatcrs admin accounts refresh-status	POST /admin/openai-accounts/{account_id}/reset-status	Admin bearer token	No by default; calls endpoint only with --execute	CrsHttpClient.reset_openai_account_status
chatcrs admin keys list	GET /admin/api-keys, optional POST /admin/api-keys/batch-stats, POST /admin/api-keys/batch-last-usage	Admin bearer token	No	CrsHttpClient.api_keys
chatcrs admin keys show	GET /admin/api-keys, optional POST /admin/api-keys/batch-stats, POST /admin/api-keys/batch-last-usage	Admin bearer token	No	CrsHttpClient.api_key_detail
chatcrs key info	GET /openai/key-info	caller CRS API key from profile or --api-key	No	CrsHttpClient.key_info
chatcrs codex token status	local tokens/Codex/<profile>.json metadata	Codex ChatEnv profile/token store	No	chatcrs.codex_direct.token_status
chatcrs codex token refresh	POST <OPENAI_OAUTH_BASE_URL>/oauth/token, default https://auth.openai.com/oauth/token	OpenAI refresh token from explicit option or envs/Codex/<profile>.env / tokens/Codex/<profile>.json	No durable mutation by default; durable refresh should use chatenv token refresh Codex <profile> so ChatEnv writes tokens/Codex/<profile>.json	chatcrs.codex_direct.refresh_access_token / chatcrs.codex_direct.refresh_chatenv_token
chatcrs codex account	access-token claims/token-store summary; best-effort GET <OPENAI_OAUTH_BASE_URL>/api/accounts probe, default https://auth.openai.com/api/accounts	OpenAI access token from option or Codex ChatEnv token store; optional refresh	No	chatcrs.codex_direct.inspect_account
chatcrs codex quota	POST <CHATGPT_BACKEND_BASE_URL>/codex/responses, default https://chatgpt.com/backend-api/codex/responses	OpenAI access token + stored/explicit account mapping	Sends minimal quota smoke; no local write	chatcrs.codex_direct.inspect_quota
chatcrs codex usage	GET <CHATGPT_BACKEND_BASE_URL>/wham/usage, default https://chatgpt.com/backend-api/wham/usage; GET <OPENAI_OAUTH_BASE_URL>/api/accounts only when no token-store account mapping exists and --account-id is omitted	OpenAI access token from option or Codex ChatEnv token store; optional refresh; profile-only use prefers tokens/Codex/<profile>.json values.account_id and otherwise auto-resolves a unique account id	No	chatcrs.codex_direct.inspect_usage

| chatcrs service install | local crs install via local_command | Current server shell | Plan by default; --execute runs locally | chatcrs.service.run_service_action | | chatcrs service update | local crs update via local_command | Current server shell | Plan by default; --execute runs locally | chatcrs.service.run_service_action | | chatcrs service start | local crs start via local_command | Current server shell | Plan by default; --execute runs locally | chatcrs.service.run_service_action | | chatcrs service stop | local crs stop via local_command | Current server shell | Plan by default; --execute runs locally | chatcrs.service.run_service_action | | chatcrs service restart | local crs restart via local_command | Current server shell | Plan by default; --execute runs locally | chatcrs.service.run_service_action | | chatcrs service status | local crs status via local_command | Current server shell | Read-only local execution by default | chatcrs.service.run_service_action | | chatcrs service switch-branch | local crs switch-branch <branch> via local_command | Current server shell | Plan by default; --execute runs locally | chatcrs.service.run_service_action | | chatcrs service update-pricing | local crs update-pricing via local_command | Current server shell | Plan by default; --execute runs locally | chatcrs.service.run_service_action |

Note: Quota smoke uses store:false, stream:true, canonical ChatGPT-Account-ID, originator: codex_cli_rs, and the default live-validated smoke model gpt-5.5. Output keeps quota headers and account-id hash only.

Configuration boundary

Field / option	Purpose	Used by
HTTP base URL profile field	CRS HTTP base URL	HTTP/Admin/API-key commands
caller API-key profile field	Caller API key	chatcrs key info
admin identity profile field	Admin username	chatcrs admin login and admin commands that need a login-derived token
admin password profile field	Admin password	chatcrs admin login and admin commands that need a login-derived token
admin bearer/session token profile field	Legacy Admin bearer token fallback	chatcrs admin ...
runtime token file	Cached login-derived Admin session token	chatcrs admin token ... and Admin auto-refresh
Codex token profile	Stable OAuth metadata in envs/Codex/<profile>.env plus runtime OAuth token values in tokens/Codex/<profile>.json	chatenv token refresh Codex <profile> and chatcrs codex ...; output is redacted and raw token values are not printed
--app-dir	Local CRS app directory on the current server	chatcrs service ...
--crs-command	Local CRS executable or command name	chatcrs service ...

The canonical CRS ChatEnv namespace is CRS; stable CRS configuration lives in Env, while dynamic Admin session tokens live in the parallel token store. Codex direct deliberately reuses ChatEnv's ChatCRS-owned Codex namespace for OAuth profile/token lifecycle instead of creating a Codex namespace. Public docs intentionally omit concrete secret values. Service-local options are CLI/Python parameters, not a second ChatEnv target namespace.

Service-local contract

chatcrs service ... exists because some lifecycle/install/update/status capabilities are not HTTP resources. The command must be installed on and executed inside the CRS server environment that owns the process and checkout.

• It does not use SSH transport or host aliases.
• It does not maintain another server from outside.
• It does not read legacy service-target environment fields or profile directories.
• For outside-server operations, use HTTP/Admin API commands. If the CRS app needs remote lifecycle control, add a CRS HTTP/Admin endpoint or a restricted host-side agent instead of hiding remote execution in ChatCRS.

Current HTTP coverage

• GET /health
• POST /web/auth/login
• GET /admin/openai-accounts
• POST /admin/openai-accounts/{account_id}/reset-status
• GET /admin/api-keys
• POST /admin/api-keys/batch-stats
• POST /admin/api-keys/batch-last-usage
• GET /openai/key-info
• OpenAI/Codex direct APIs used by chatcrs codex ...: POST https://auth.openai.com/oauth/token, GET https://auth.openai.com/api/accounts, GET https://chatgpt.com/backend-api/wham/usage, and POST https://chatgpt.com/backend-api/codex/responses.

Explicit gaps / out-of-scope task surfaces

Gap or removed surface	Current handling
API key create/update/delete/restore/tag/index	Confirm or add Admin HTTP endpoints first, then implement with dry-run/execute and redacted audit rules
account add/delete/toggle/schedulable/test	Confirm or add Admin HTTP endpoints first; do not substitute local scripts or direct database writes for external management
topology/edge/Redis/Nginx/release/cutover	Deployment/operations-layer work, outside the ordinary CRS HTTP client and outside this service restore
verify/image/debug surfaces	Kept out of ChatCRS package CLI; handle as separate acceptance/proxy-site/runbook tasks when scoped

Update rules

• Every registered leaf must appear on this page with its interface, auth source, mutation boundary, and Python API.
• HTTP/Admin commands must name the endpoint.
• Service commands must remain server-local and explicit about local_command execution.
• Keep all outputs redacted: API keys, tokens, passwords, and OAuth credentials are reported only as presence, counts, status, or [REDACTED].

Banked Codex resets

chatcrs codex reset list reads available count and expirations with GET /wham/rate-limit-reset-credits, without model generation or OAuth refresh. 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.

CLI	HTTP	Python API
chatcrs codex reset list	GET /wham/rate-limit-reset-credits	inspect_reset_credits
chatcrs codex reset consume	POST /wham/rate-limit-reset-credits/consume; GET readback	consume_reset_credit