nanobot/docs/cli-reference.md

CLI Reference

Use this page when you know what you want to run and need the command shape. For a guided first run, start with quick-start.md.

Choose a Command

Goal	Command	Notes
Check the install	nanobot --version	If this fails, try python -m nanobot --version
Create or refresh config	nanobot onboard	Creates ~/.nanobot/config.json and ~/.nanobot/workspace/
Use guided setup	nanobot onboard --wizard	Best when you prefer prompts over hand-editing JSON
Check config without calling a model	nanobot status	Reads the default config and summarizes the active model/provider
Send one test message	nanobot agent -m "Hello!"	First proof that install, config, provider, model, and workspace all work
Chat in the terminal	nanobot agent	Interactive local chat; exit with exit, /exit, :q, or Ctrl+D
Use WebUI or chat apps	nanobot gateway	Keep this terminal running, or use nanobot gateway --background
Deliver a local external trigger	nanobot trigger <id> "message"	Created first with /trigger <name> in the target chat/session
Serve an OpenAI-compatible API	nanobot serve	Starts /v1/chat/completions, /v1/models, and /health
Check chat channel setup	nanobot channels status	Useful before starting nanobot gateway
Log in to QR/OAuth-style channels	nanobot channels login <channel>	Used by channels such as WhatsApp and WeChat
Log in to OAuth model providers	nanobot provider login <provider>	Used by OAuth providers such as OpenAI Codex and GitHub Copilot

Global

nanobot --help
nanobot --version
python -m nanobot --help
python -m nanobot --version

python -m nanobot ... is useful when the package is installed but the nanobot script is not on PATH.

Common Patterns

Most day-to-day commands use the default config and workspace. Advanced or multi-instance runs usually pass both paths explicitly:

nanobot agent --config ./bot-a/config.json --workspace ./bot-a/workspace -m "Hello"
nanobot gateway --config ./bot-a/config.json --workspace ./bot-a/workspace
nanobot serve --config ./bot-a/config.json --workspace ./bot-a/workspace

Use --verbose on long-running processes when you need startup or runtime logs:

nanobot gateway --verbose
nanobot serve --verbose

Long-running commands keep working until you stop them. Press Ctrl+C in that terminal to stop foreground nanobot gateway or nanobot serve. If you started the gateway with --background, use nanobot gateway stop.

Setup

Command	Description
nanobot onboard	Initialize or refresh the default config and workspace
nanobot onboard --wizard	Use the interactive setup wizard
nanobot onboard --config <path> --workspace <path>	Initialize or refresh a specific instance

Default paths:

Path	Default
Config	~/.nanobot/config.json
Workspace	~/.nanobot/workspace/

Agent CLI

Command	Description
nanobot agent -m "Hello!"	Send one message and exit
nanobot agent	Start interactive terminal chat
nanobot agent --session <id>	Use a specific session key
nanobot agent --workspace <path>	Override workspace
nanobot agent --config <path>	Use a specific config file
nanobot agent --no-markdown	Print plain text instead of Rich-rendered Markdown
nanobot agent --logs	Show runtime logs while chatting

Interactive mode exits with exit, quit, /exit, /quit, :q, or Ctrl+D.

Gateway

nanobot gateway starts enabled chat channels, WebUI/WebSocket when configured, cron-backed system jobs, Dream, heartbeat, and the health endpoint. By default it runs in the foreground, which keeps existing scripts and terminal workflows unchanged. Use --background when you want a local macOS, Linux, or Windows process that you can manage from the CLI.

Command	Description
nanobot gateway	Start the gateway in the foreground with config defaults
nanobot gateway --verbose	Show verbose runtime output
nanobot gateway --port <port>	Override gateway.port for the health endpoint
nanobot gateway --workspace <path>	Override workspace
nanobot gateway --config <path>	Use a specific config file
nanobot gateway --background	Start the gateway as a background process
nanobot gateway status	Show the recorded background gateway PID, state file, and log file
nanobot gateway logs --no-follow	Print recent background gateway logs and exit
nanobot gateway logs	Follow background gateway logs
nanobot gateway restart	Restart the recorded background gateway with the current config
nanobot gateway stop	Stop the recorded background gateway
nanobot gateway install-service	Install a systemd user service or macOS LaunchAgent
nanobot gateway install-service --dry-run	Preview the generated service file and system commands
nanobot gateway uninstall-service	Remove the installed system service

For custom instances, pass the same selector flags to management commands:

nanobot gateway --background --config ./bot-a/config.json --workspace ./bot-a/workspace
nanobot gateway status --config ./bot-a/config.json --workspace ./bot-a/workspace
nanobot gateway stop --config ./bot-a/config.json --workspace ./bot-a/workspace
nanobot gateway install-service --config ./bot-a/config.json --workspace ./bot-a/workspace --name bot-a

--background is a lightweight detached process. install-service is for login/startup integration: Linux uses a systemd user service; macOS uses a LaunchAgent plist. System services run the foreground gateway under the OS supervisor rather than nesting another background process.

Default health endpoint:

http://127.0.0.1:18790/health

The bundled WebUI is served by the WebSocket channel, usually on port 8765, not by the gateway health endpoint.

Local Triggers

nanobot trigger delivers one local message to a trigger that was created from a chat/session with /trigger <name>.

nanobot trigger trg_8K4P2Q9X "Review PR #4502"

Keep nanobot gateway running so the message can be delivered to the linked chat/session.

The command writes to a workspace-local durable queue. If nanobot gateway is not running yet, the message waits in that workspace. If the gateway exits after claiming a delivery but before completing it, the next gateway start requeues that delivery. The queue is at-least-once, not exactly-once, so the same message can be delivered again after an interrupted process. Run one gateway consumer per workspace; this local queue is not a distributed multi-consumer queue.

Use stdin when another local process generates the message:

generate-report | nanobot trigger trg_8K4P2Q9X

Options:

Command	Description
nanobot trigger <id> "message"	Deliver one message through a trigger
nanobot trigger <id>	Read the message from stdin
nanobot trigger --config <path> <id> "message"	Use the workspace from a specific config
nanobot trigger --workspace <path> <id> "message"	Use a specific workspace

Triggers are managed in the WebUI Automations view instead of through separate list, revoke, or delete CLI subcommands. From there you can pause/resume, rename, delete, search, and copy the command for each trigger.

For webhooks or other external systems, run your own small service and have it call this CLI after it decides what message nanobot should receive.

OpenAI-Compatible API

Command	Description
nanobot serve	Start /v1/chat/completions, /v1/models, and /health
nanobot serve --host <host>	Override API bind host
nanobot serve --port <port>	Override API port
nanobot serve --timeout <seconds>	Override per-request timeout
nanobot serve --verbose	Show runtime logs
nanobot serve --workspace <path>	Override workspace
nanobot serve --config <path>	Use a specific config file

Default API endpoint:

http://127.0.0.1:8900

See openai-api.md for request examples.

Status

nanobot status

Shows the default config path, workspace path, active model, and provider summary. This command does not currently accept --config; use explicit --config and --workspace on agent, gateway, or serve when debugging a specific instance.

Channels

Command	Description
nanobot channels status	Show configured channel status
nanobot channels status --config <path>	Show channel status for a specific config
nanobot channels login <channel>	Run interactive login for supported channels
nanobot channels login <channel> --force	Re-authenticate even if credentials already exist
nanobot channels login <channel> --config <path>	Use a specific config file

Examples:

nanobot channels login whatsapp
nanobot channels login weixin
nanobot channels status

See chat-apps.md for channel-specific setup.

Provider OAuth

Command	Description
nanobot provider login openai-codex	Authenticate OpenAI Codex provider
nanobot provider login github-copilot	Authenticate GitHub Copilot provider
nanobot provider logout openai-codex	Remove OpenAI Codex OAuth state
nanobot provider logout github-copilot	Remove GitHub Copilot OAuth state

See providers.md for when OAuth providers need explicit provider/model selection.

Useful First Checks

nanobot --version
nanobot status
nanobot agent -m "Hello!"

If these fail, use troubleshooting.md before debugging WebUI, chat apps, Docker, systemd, or SDK integrations.