buildwithnexus

CLI Reference

buildwithnexus is a single static binary — a fast coding agent that lives in your terminal. It plans, reads and edits files, and runs commands, asking before each change. Run it with the full name or the short alias bwn.

npm install -g buildwithnexus
buildwithnexus            # or: bwn

Running with no arguments opens the interactive REPL. Pass a subcommand to go headless.

Top-Level Commands

run <task>
Run a task headlessly in BUILD mode and print the result.
plan <task>
Decompose a task into steps you approve, then execute them.
brainstorm <idea>
Free-form chat with the model. No tools, no file changes.
continue
Resume the most recent session and keep going.
resume <id>
Restore a specific saved session by its id.
sessions
List saved session transcripts from ~/.buildwithnexus/sessions.
init
Set up keys, detect local models, and write config.
providers
Show built-in providers and which ones are configured.
doctor
Diagnose setup: check keys, external tools, and API connectivity.
version
Print the binary version.

| Command | Description | |---------|-------------| | buildwithnexus | Open the interactive REPL | | buildwithnexus run <task> | Execute a task headlessly (agentic BUILD loop) | | buildwithnexus plan <task> | Plan into approved steps, then execute | | buildwithnexus brainstorm <idea> | Free-form chat, no tools | | buildwithnexus continue | Resume the most recent session | | buildwithnexus resume <id> | Resume a specific session by id | | buildwithnexus sessions | List saved sessions | | buildwithnexus init | Configure keys, providers, and local models | | buildwithnexus providers | List built-in providers and their status | | buildwithnexus doctor | Diagnose setup (keys, tools, connectivity) | | buildwithnexus version | Show version |

Modes

The same three modes are available from subcommands and from inside the REPL.

Plan
Decompose & approve
Breaks the task into concrete steps you approve before any of them run.
Build
Agentic ReAct loop
Loops over tools — read_file, list_dir, write_file, edit_file, run_command, finish.
Brainstorm
Free-form chat
Conversation only — no tools, no file changes.

The REPL

Running buildwithnexus with no arguments drops you into an interactive shell that renders inline on the normal terminal screen — so native scroll, select, and copy all work. Edits show inline colored diffs, and tokens stream as they arrive.

Slash Commands

| Command | Description | |---------|-------------| | /help | Show available commands | | /clear | Clear the screen | | /new | Start a fresh session | | /resume | Pick a saved session to restore and continue | | /init | Run setup (keys, providers, local-model detection) | | /exit | Leave the REPL (/quit also works) | | /model [name] | Hot-swap the AI model mid-session; persists to settings | | /compact | Compress the transcript to free up token budget | | /review | AI code review of the current git diff | | /commit | AI-drafted conventional commit message for staged changes | | /pr | AI-drafted pull request title and description | | /schedule <delay> <task> | Run a task once in the background after a delay (e.g. 5s, 2m, 1h) | | /loop <interval> <task> | Run a task repeatedly in the background at a fixed interval | | /workflows | List and manage background workflows; c<id> to cancel, i<id> to inspect output | | /btw <context> | Inject silent context into the next agent turn without interrupting | | /config | Configure hooks, memory, and commands via AI | | /memory | View and edit session memory | | /skills | List available skills and custom slash commands |

Shell Mode

Prefix a line with ! to run it directly in your shell without leaving the REPL.

! git status
! cargo test

Input Editor

The input line is a full editor, not a plain prompt.

Multi-line input
End a line with \ then Enter to continue onto the next line.
Tab completion
Complete / commands and @ file paths with Tab.
Reverse search
Ctrl+R searches backward through your persistent history.
Kill-ring
Cut and yank text with the usual readline-style kill-ring.
Open in $EDITOR
Ctrl+G opens the current input in your $EDITOR for longer prompts.
Persistent history
History is saved across runs under ~/.buildwithnexus.

Permission Modes

Mutating tools are gated. Pick how aggressively buildwithnexus is allowed to act.

ask
Default
Confirm before each file edit or command.
auto
Act without prompting — but sensitive paths and catastrophic commands still require confirmation.
readonly
Reads and commands only — no writes or edits.

Guardrails hold in every mode: file tools are confined to the working directory, sensitive paths (~/.ssh, .env, *.pem, the key store) and catastrophic commands always prompt, API keys are never sent to a non-HTTPS endpoint, and key-like tokens are redacted from surfaced errors.

Headless & Automation

Every mode has a headless subcommand. Add --json to emit one structured event per line — ideal for scripts and CI.

buildwithnexus run "add a --verbose flag to the CLI"
buildwithnexus plan "migrate the test suite to vitest"
buildwithnexus run "summarize recent changes" --json

{"type":"tool_call","name":"read_file","input":{"path":"src/main.rs"}}
{"type":"tool_result","name":"read_file","content":"fn main() {…","is_error":false}
{"type":"assistant","text":"Added the --verbose flag."}
{"type":"finish","summary":"Added the --verbose flag."}

Models & Providers

Use a remote model via API key, or a local model on your machine. Eight built-in providers span two wire protocols.

Remote
Anthropic · OpenAI · OpenRouter · Groq · Hugging Face
Anthropic Messages, plus OpenAI chat-completions (which also covers the rest).
Local
Ollama · llama.cpp server · LM Studio
Auto-detected at setup via the Ollama API and a GGUF folder scan.

Run buildwithnexus init to configure keys and detect local models, or buildwithnexus providers to see what's available.

Sessions

Every run's transcript is saved under ~/.buildwithnexus/sessions. Resume from the CLI or from inside the REPL with /resume. When the context nears the model's window it auto-compacts so long sessions keep going.

buildwithnexus sessions          # list saved sessions
buildwithnexus continue          # resume the most recent
buildwithnexus resume <id>       # resume a specific session