CLI reference

Every command and option of npx binference, what an agent's folder holds, and how to update it.

Run each command as npx binference <command>. Every command takes --help. The CLI needs macOS or Linux (on Windows, WSL2) and Node.js 22 or newer.

Command	What it does
`agent-os <name>`	Sets up a folder for one agent. See Set up an agent
`start`	Starts the folder's app on bInference. `./start` in the folder does the same, faster
`doctor [folder]`	Checks the folder end to end and says what to fix
`link-wallet [folder]`	Links the agent's wallet for a track record. You sign; nothing moves

agent-os

npx binference agent-os my-agent --app codex --model deepseek/deepseek-v4.1-flash

Option	What it does
`--app claude`, `codex`	Which app runs the agent. Needed without a terminal when both are installed
`--model <id>`	The model it starts on, any id on Models
`--yes`, `-y`	Installs Binance's wallet tool, `baw`, without asking
`--sandbox`	Turns on Claude Code's sandbox. Approve Binance's and binference.io's hosts the first time
`--no-wait`	Shows the sign-in code and stops
`--resume`	Finishes a setup started with `--no-wait`
`--json`	Prints JSON events instead of text

start

Arguments after start go to the app. To pick up Claude Code's last conversation:

./start --continue

Put -- first to pass --help to the app: ./start -- --help.

doctor

npx binference doctor --fix --dry-run

Option	What it does
`--fix`	Repairs what failed. Your own settings, hooks and MCP servers stay
`--dry-run`	With `--fix`, shows what would change and changes nothing
`--json`	Prints the result as one JSON object

The folder

Path	What it holds
`.binference/key`	The agent's key, readable by your user only. Ignored by git
`.binference/config.json`	Its cockpit, app and model
`.binference/hooks/`	The hooks that apply your limits, and the launcher
`start`	Starts the app with the key
`AGENTS.md`, `CLAUDE.md`	The house rules
`.claude/` and `.mcp.json`, or `.codex/`	The app's settings, hooks and skills

Nothing outside the folder changes, except baw if you install it, and Binance's MCP Server if you connect it with Codex, which adds it for every Codex session on the computer.

Update a folder

A folder keeps the hooks it was set up with. After a new release, run this in the folder:

npx binference@latest doctor --fix

Keep @latest: plain npx binference may run a copy npx saved earlier. Releases are listed on npm.

From an agent or a script

The CLI works the same when an agent runs it.

Nothing prompts without a terminal. Choices come from flags, and nothing is installed without --yes.

--json writes only JSON to stdout. An error looks like this:

{ "ok": false, "error": { "code": "usage", "message": "...", "hint": "..." } }

Exit codes: 0 done, 1 failed (for doctor, a check failed), 2 wrong usage.
link-wallet runs only in a terminal, so an agent can never sign with the wallet.

An agent can set up another agent for you. It runs:

npx binference agent-os scout --app claude --no-wait --json

The first event carries the code and the address to approve it:

{
  "event": "approval_required",
  "user_code": "WDJB-MJHT",
  "url": "https://binference.io/link?code=WDJB-MJHT",
  "expires_at": "..."
}

The agent passes them on to you. Within 10 minutes, you check the code and approve it with your wallet. Then the agent finishes the setup:

npx binference agent-os scout --resume

agent-osCopy Anchor Link

startCopy Anchor Link

doctorCopy Anchor Link

The folderCopy Anchor Link

Update a folderCopy Anchor Link