# CLI

The `hyphen` CLI talks to the gateway from your terminal. It chats, explains
code, writes commit messages, reviews diffs, runs prompts in bulk, configures
coding agents, and exposes Hyphen to agents over MCP.

It is built for agents as much as for people. Every command takes `--json`,
stdout carries only data, and `hyphen help --agent` prints a full machine
reference an agent can read before deciding what to run.

## Install

Use whichever package manager you already have. All four are tested.

```bash
npm  install -g @hyphen_solution/cli
pnpm add    -g @hyphen_solution/cli
yarn global add @hyphen_solution/cli
bun  add    -g @hyphen_solution/cli
```

Node 20 or newer. The package has no runtime dependencies, so the install is
one small download and nothing is compiled.

Run it once without installing anything:

```bash
npx @hyphen_solution/cli models
pnpm dlx @hyphen_solution/cli models
yarn dlx @hyphen_solution/cli models
bunx @hyphen_solution/cli models
```

That form is the one to use in CI, where a global install is usually wasted
work.

## Sign in

```bash
hyphen login
```

It prompts for your key with the echo turned off, checks the key against the
gateway, and only saves it if it works. Credentials go to
`~/.hyphen/config.json` with mode `0600`.

For CI, skip the prompt:

```bash
hyphen login --key "sk-..."
```

Or set `HYPHEN_API_KEY` and skip login entirely. The order of precedence is
`--key`, then `HYPHEN_API_KEY`, then the config file. Check what is in effect
with `hyphen whoami`, which masks the key before printing it.

## Chat

Run it with no arguments for an interactive session:

```bash
hyphen chat
```

You get history, streamed replies, and a few slash commands: `/model` to switch
model mid-thread, `/system` to set a system prompt, `/save` to write the
transcript out, `/tokens` for what the session has spent, `/exit` to leave. The
thread is saved on the way out.

Or send one prompt and get one answer:

```bash
hyphen chat "explain the borrow checker in two sentences"
```

Follow-up questions need the previous turn, so pass `-c` to continue the last
thread:

```bash
hyphen chat "what is a lifetime annotation?"
hyphen chat "give me an example" -c
```

Attach files, pipe input, or both. With a prompt argument and piped stdin, the
argument is the instruction and stdin is the context:

```bash
hyphen chat "find the bug" --file src/api.ts,src/db.ts
hyphen chat "summarise this" < README.md
```

Stream the reply as it arrives:

```bash
hyphen chat "write a haiku about caching" --stream
```

Token counts and warnings go to stderr, so stdout stays clean for piping:

```bash
hyphen chat "list three colours" --json | jq -r .content
```

:::tip[Reasoning is hidden by default]
These models think before they answer. When streaming, that deliberation
arrives inline wrapped in `<think>` tags. The CLI strips it so streamed and
non-streamed output match. Pass `--show-reasoning` to see it on stderr.
:::

## The everyday commands

Three things people ask a model for constantly, without writing the prompt each
time.

**Explain a file, or diagnose whatever just broke.** It reads the input and
works out which of the two you meant:

```bash
hyphen explain src/api.ts
npm test 2>&1 | hyphen explain
cargo build 2>&1 | hyphen explain
```

**Write the commit message.** It reads your staged diff and prints a message.
Add `--apply` to commit with it:

```bash
hyphen commit
hyphen commit --apply
```

**Review before you push.** Working tree by default, or a whole branch:

```bash
hyphen review
hyphen review --against main --stream
```

A review is a second opinion, not a gate. It will miss things and it will
sometimes be confidently wrong, so read the diff yourself too.

## Run a lot of prompts at once

`hyphen batch` is for unattended work: a file of prompts in, JSONL out.

```bash
hyphen batch prompts.txt --output results.jsonl
```

Input is one prompt per line, or JSONL with `{"id","prompt"}` and optional
`system` and `model` per record. The two forms can be mixed in one file. Every
result carries its `id`, so results match back to inputs no matter what order
they finish in.

Apply one instruction across every line with a template:

```bash
hyphen batch titles.txt \
  --template "Write a one-line summary of: {{input}}" \
  --concurrency 8 \
  --output summaries.jsonl
```

It is built to survive a long run. Transient failures are retried with
exponential backoff. A single bad prompt is recorded as a failed record and the
run continues. If it dies halfway, `--resume` reads the output file and skips
what already succeeded:

```bash
hyphen batch prompts.txt --output results.jsonl --resume
```

:::tip[It stops when the budget is gone]
If your monthly allowance runs out mid-run, the batch stops immediately instead
of firing hundreds of requests that would all fail the same way. Exit code 5
tells you that is what happened, and `--resume` picks up from there once your
allowance resets or you top up credit.
:::

Progress, token totals and the final summary go to stderr, so stdout stays
clean:

```bash
hyphen batch prompts.txt --json | jq '.usage.total_tokens'
```

## Coming from another provider

```bash
hyphen migrate
```

It looks at the usual environment variables and at the config files of every
tool below, works out what you are currently pointed at, and prints the exact
command to repoint each one. Anything already using Hyphen is skipped. Nothing
is changed until you run one of the commands it suggests.

It detects only that a credential exists. It never reads, prints or sends the
value of another provider's key.

Keep your old keys. Running two providers side by side is fine, and going back
is the same one line in reverse.

## Configure a coding agent

`hyphen setup` writes working configuration for eleven tools, including the
specific detail that breaks each one:

```bash
hyphen setup --list          # what it knows how to configure
hyphen setup claude-code     # print the config
hyphen setup claude-code --write
```

To do every tool you actually have installed in one command:

```bash
hyphen setup --all           # show what was found, change nothing
hyphen setup --all --write --with-key
```

`--all` only touches tools whose config already exists on your machine, so it
will not leave settings files behind for software you do not run.

Writing is careful about files you already have. JSON configs are deep-merged,
a `.hyphen.bak` backup is kept, and anything that would corrupt the file is
refused with an explanation instead. A second run is skipped unless you pass
`--force`.

Your real key is not printed by default. The output uses `sk-YOUR_KEY` as a
placeholder, and `--with-key` inlines the real one when you want that.

## Diagnose a problem

```bash
hyphen doctor
```

Six checks run in order: credentials present, gateway reachable, key accepted,
catalog readable, a real completion round-trip with its latency, and whether
this machine has hit a budget limit recently. Each one passes or fails on its
own line, and the exit code is the first failure's code.

## Serve Hyphen over MCP

`hyphen mcp` runs an MCP server on stdio, which lets an MCP-aware agent call
the gateway as a tool. It exposes `hyphen_chat`, `hyphen_list_models`, and
`hyphen_check_budget`.

Register it with Claude Code:

```bash
claude mcp add hyphen -- hyphen mcp
```

Or add it to any client that reads an `mcpServers` block:

```json
{
  "mcpServers": {
    "hyphen": {
      "command": "hyphen",
      "args": ["mcp"],
      "env": { "HYPHEN_API_KEY": "sk-..." }
    }
  }
}
```

## Exit codes

Scripts can branch on the exit code instead of parsing text.

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | Unexpected error |
| 2 | Bad usage, such as an unknown flag |
| 3 | No key configured |
| 4 | Key rejected |
| 5 | Rate limited, either budget or fair use |
| 6 | Gateway unreachable |
| 7 | Other client error |
| 8 | Server error |

A `5` tells you which kind it was. A budget limit lasts until your allowance
resets and the message carries the reset date. A fair-use limit clears after a
short backoff. See [Rate limits](/rate-limits).

## Pointing an agent at the CLI

If you want an agent to use Hyphen without reading these docs, give it the
machine reference:

```bash
hyphen help --agent
```

That prints every command, flag, JSON shape, and exit code, plus the model
constraints worth knowing. It is written to be pasted straight into an agent's
context.

## Related

- [Quickstart](/quickstart) — the first request, without the CLI.
- [Connect your coding agent](/agents/claude-code) — the full guide per tool.
- [Rate limits](/rate-limits) — what a 429 means and how to handle it.