Copy page

Get Started

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.

Code
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:

Code
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

Code
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:

Code
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:

Code
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:

Code
hyphen chat "explain the borrow checker in two sentences"

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

Code
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:

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

Stream the reply as it arrives:

Code
hyphen chat "write a haiku about caching" --stream

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

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

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:

Code
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:

Code
hyphen commit
hyphen commit --apply

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

Code
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.

Code
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:

Code
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:

Code
hyphen batch prompts.txt --output results.jsonl --resume

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

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

Coming from another provider

Code
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:

Code
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:

Code
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

Code
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:

Code
claude mcp add hyphen -- hyphen mcp

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

Code
{
  "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.

Pointing an agent at the CLI

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

Code
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 — the first request, without the CLI.
• Connect your coding agent — the full guide per tool.
• Rate limits — what a 429 means and how to handle it.