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

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

Default paths:

Agent CLI

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

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.

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:

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

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.

Channels

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.

The plugins command name is retained for compatibility, but these entries are nanobot runtime support packages, not the user-invokable tools shown in WebUI Apps. They cannot be attached to a chat turn with @.

Document and PDF reading are included in the standard installation. The old nanobot plugins enable documents and nanobot plugins enable pdf commands remain accepted as no-op compatibility aliases.

Provider OAuth

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.