# CLI

```bash
npx brynth <command> [options]
```

Node.js 22.12 or later. Exit codes: `0` success, `1` error, `2` wrong usage.

## Global options

| Option | Meaning |
|---|---|
| `--json` | One JSON object on stdout, nothing else |
| `--project <id\|slug>` | Project to use; default: the last one created |
| `--api-url <url>` | API base URL; default `BRYNTH_API_URL`, then the URL saved with the project, then `https://api.brynth.ai` |
| `-y, --yes` | Do not ask; use defaults and flags |
| `-h, --help` | Help for the command |
| `--version` | Print the CLI version |

## init

```bash
npx brynth init [--email <address>] [--name <name>] [--slug <slug>]
                [--client <list>] [--no-skill] [--telegram | --no-telegram]
```

Signs you in by email, creates a project, saves its admin key, connects the clients, installs the skill, creates an email source and a test webhook, and prints a test request. See [Quickstart](/quickstart.md).

- `--client` takes `claude-code`, `codex`, both comma-separated, or `none`. Asked in a terminal (default both); with `--yes` no client is connected unless named; without a terminal and without `--yes`, `--client` is required.
- With `--yes`, `--email` is required.
- `--name` defaults to the folder name, `--slug` to a slug derived from the name.
- The skill is installed for the chosen clients, including any that could not be connected, unless you pass `--no-skill`.
- Telegram: in a terminal, `init` asks (Enter skips); `--telegram` links it without asking, `--no-telegram` skips the question. With `--yes` or without a terminal it is skipped unless you pass `--telegram`.
- An account can have up to 3 projects: one more fails with `PROJECT_LIMIT_REACHED`.
- If a step fails after the project is created, `init` prints the commands that finish the setup.
- A client that cannot be connected does not stop `init`: the summary lists it under `Failed` with the command to retry. With `--json`, `clients` lists the connected clients, `clients_failed` the others, `skill` the skill files written and `skill_failed` the clients whose skill could not be installed.

## connect

```bash
npx brynth connect <claude-code|codex> [--server-name <name>] [--force]
```

Creates a key for the client (all scopes; label, agent and platform set to the client name) and writes it in the client's configuration. With `BRYNTH_KEY` set, it uses that key, creates none and records nothing in `credentials.json`.

- `--server-name` names the MCP server (default `brynth`): letters, digits, `_` and `-`, up to 64 characters.
- If the server already exists, the CLI asks before replacing it; `--force` replaces it without asking. With `--yes` or without a terminal, it stops unless you pass `--force`.

See [Claude Code](/get-started/claude-code.md) and [Codex](/get-started/codex.md).

## skill install

```bash
npx brynth skill install [--client claude-code,codex] [--check]
```

Writes the Brynth skill in the current folder: `.claude/skills/brynth/SKILL.md` for Claude Code, `.agents/skills/brynth/SKILL.md` for Codex. Without `--client`, it installs for the agents connected to the project, otherwise for both. `--check` writes nothing and exits with `0` if the skill is current, `1` otherwise.

## status

```bash
npx brynth status [--project <id|slug>] [--json]
```

The project, its API and MCP URLs, the key in use, sources and addresses, channels, active keys and the oldest pending events (up to 5). Works with any key: a section the key cannot read says which scope it needs. Key ids are in the `--json` output.

## key create

```bash
npx brynth key create --scopes <a,b> [--label <text>] [--agent <label>] [--platform <name>] [--json]
```

Creates a key with the saved admin key, or with `BRYNTH_KEY` if it has the `admin` scope. The token is printed once.

- `--scopes` is required: a comma-separated list of `inbox:read`, `inbox:write`, `send`, `disk`, `approvals`, `ledger:read`, `admin`.
- `--platform` fixes the platform on the key, for example `claude-code` or `codex`; alone, it sets the agent to the same name, lower-cased. Name the client that will use the key: a client whose `session_hello` sends another identity gets an `IDENTITY_CONFLICT` warning and the key keeps its own.
- The output ends with the `connect` command for the key's client on another computer (`claude-code` or `codex`, or either for a key with no platform yet). See [Use a project from another machine](/guides/another-machine.md).
- `--agent` fixes the agent name and needs `--platform`.
- Without `--agent` and `--platform`, the first `session_hello` sets the key's identity.

## logs

```bash
npx brynth logs [--limit 20] [--op <op>] [--project <id|slug>] [--json]
```

The latest ledger entries, newest first: time, operation, actor, subject, outcome. `--limit` takes 1 to 500 (default 20). `--op` keeps one operation, by its exact name, for example `source.added`. Needs a key with `ledger:read`.

## Environment

| Variable | Use |
|---|---|
| `BRYNTH_API_URL` | API base URL |
| `BRYNTH_KEY` | Use this key instead of the saved credentials |
| `BRYNTH_CONFIG_DIR` | Where `credentials.json` lives; default `$XDG_CONFIG_HOME/brynth`, then `~/.config/brynth` |
| `CODEX_HOME` | Codex configuration folder; default `~/.codex` |