hkuds--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/
Refresh config non-interactively	nanobot onboard --refresh	Preserves existing values and adds missing default fields without prompting
Use guided setup	nanobot onboard --wizard	Best when you prefer prompts over hand-editing JSON
Open the browser workbench	nanobot webui	Prepares local WebUI settings, starts the gateway, and opens the browser
Check config without calling a model	nanobot status	Summarizes the selected config, workspace, active model, and providers
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
Run the gateway directly	nanobot gateway	Service/ops command for WebUI, chat apps, cron, and heartbeat
Deliver a local 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
Manage optional features	nanobot plugins list	Shows channels and optional capabilities you can turn on
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 --refresh	Refresh an existing config without prompting, preserving existing values
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

In interactive mode, Enter sends the current message. Press Alt+Enter to add a newline before sending.

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

WebUI

Command	Description
nanobot webui	Create config/workspace if needed, enable the local WebUI channel after confirmation, start the gateway, and open http://127.0.0.1:8765
nanobot webui --background	Start or reuse a background gateway, then open the WebUI
nanobot webui --no-open	Prepare and start the WebUI without opening a browser
nanobot webui --port <port>	Set the WebUI/WebSocket port
nanobot webui --gateway-port <port>	Override the gateway health port
nanobot webui --yes	Apply safe localhost WebUI defaults without confirmation; provider credentials still require interactive setup

First-run WebUI setup binds to 127.0.0.1 by default. Use manual configuration and a WebUI password before exposing the WebSocket channel beyond localhost.

Gateway

nanobot gateway starts enabled chat channels, WebUI/WebSocket when configured, cron-backed system jobs, Dream, heartbeat, and the health endpoint. Most local browser users should start with nanobot webui; use gateway directly for service management, chat app operation, and advanced deployment. 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 message is recorded as an automation turn in that session, not as a normal chat message typed by the user.

The command writes to a workspace-local durable queue. If nanobot gateway is not running yet, the message waits in that workspace. If the target session is already running a turn, the trigger waits for that session to become idle. If the gateway exits after claiming a delivery but before the linked turn completes, 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. If the agent receives the delivery and the turn fails, the delivery is marked failed instead of retried indefinitely. Each delivery also writes an audit record under <workspace>/triggers/runs. 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.

See Automations for the broader automation model, WebUI management, and delivery behavior.

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

Public binds (0.0.0.0 or ::) require api.apiKey; send it as a Bearer token on API routes.

See openai-api.md for request examples.

Status

nanobot status

Shows the config path, workspace path, active model, and provider summary without calling a model.

Command	Description
nanobot status	Inspect the default instance
nanobot status --config <path>	Inspect a specific config
nanobot status --config <path> --workspace <path>	Inspect a specific config with a workspace override

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
nanobot plugins list --config <path>	Show plugin/channel enabled state for a specific config

Examples:

nanobot channels login whatsapp
nanobot channels login weixin
nanobot channels status

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

Optional Features

Use these commands when you want nanobot to add or remove a built-in capability without hand-editing JSON. Enabling may install the support package first. Disabling is for channels such as Telegram, Matrix, or Slack; it keeps your saved settings and turns the channel off.

Command	Description
nanobot plugins list	Show available channels and optional capabilities
nanobot plugins enable <name>	Install missing support and enable the feature or channel
nanobot plugins enable <name> --logs	Show package install logs while enabling
nanobot plugins disable <channel>	Turn off a channel without deleting its saved settings
nanobot plugins list --config <path>	Read a specific config file
nanobot plugins enable <name> --config <path>	Update a specific config file
nanobot plugins disable <channel> --config <path>	Turn off a channel in a specific config file

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.