Commands - Chert

Run the installed CLI with npx --no-install chert. Always pass an explicit --config path to commands that use a configuration. Add --json for structured diagnostics.

Common commands

Command	Purpose
`chert --help` / `chert --version`	Show usage or the installed version.
`chert init --mode byor`	Create a BYOR config and TypeScript callback scaffold.
`chert init --mode create-room`	Configure the optional LiveKit room/dispatch adapter.
`chert check`	Check configuration, health, storage, and outstanding recovery without allocating sessions.
`chert byor`	Run the receiver wrapper with your application callbacks.
`chert create-room`	Run the connector that creates rooms on incoming calls.
`chert status`	Read saved local state; does not check live agent readiness.
`chert projects` / `chert lines` / `chert bindings`	Inspect the projects, lines, and connector enrollments available to you.
`chert enroll`	Create a standby binding and save connection credentials.
`chert activate`	Explicitly route new calls to the enrolled connector.
`chert drain`	Stop new assignments and restore the saved webhook route.
`chert revoke`	Permanently revoke normal access; retain scoped recovery for previously owned calls.

These are command summaries, not complete invocations. See the BYOR, create-room, and enrollment guides for required flags. chert run is only for legacy v1 configs; new configs use their explicit mode command.

Check and inspect

npx --no-install chert check --config "$PWD/chert.enrolled.json" --json
npx --no-install chert status --config "$PWD/chert.enrolled.json" --json

check currently exits 3 because its diagnostics are partial. Read individual results. status is a saved observation; a connected transport or healthy process is not proof of working call audio.

Recover unfinished work

After stopping the original writer, use its original config, state directory, and compatible application code:

npx --no-install chert byor --config "$PWD/chert.enrolled.json" --recovery --json

For create-room mode, substitute create-room. Recovery must settle the original operation and verify cleanup. There is no clear-debt command: unresolved cleanup blocks new admission, and deleting state loses the evidence needed to recover safely.

Understand failures

Diagnostic	Meaning / next step
`mode_mismatch`	Use the runtime command matching the config’s mode.
`handler_invalid`	Check the BYOR module path, compiled output, and exported handler.
`credentials_invalid`	Check the credential source and binding authorization.
`deadline_exceeded`	Preparation missed its original deadline; inspect agent/session startup time.
`acceptance_uncertain`	The decision outcome is unknown; reconcile instead of creating another session.
`application_lifecycle_pending`	Application processing has not durably acknowledged a call event.
`cleanup_pending`	Verify cleanup through the original application’s recovery logic.

Exit code	Meaning
`0`	Success
`1`	Internal failure
`2`	Configuration or usage error
`3`	Partial diagnostics or outstanding recovery
`4`	State directory or writer error
`5`	Unsupported runtime or platform
`6`	Transport or backend failure