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

# Commands

> Common CLI commands and what their results mean.

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](/facetime-cli/byor), [create-room](/facetime-cli/create-room), and [enrollment](/facetime-cli/connect) guides for required flags. `chert run` is only for legacy v1 configs; new configs use their explicit mode command.

## Check and inspect

```bash theme={null}
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:

```bash theme={null}
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 |