mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-06-15 15:24:06 +00:00
4a58b83acc
* docs: make onboarding friendlier for beginners * docs: build clearer documentation paths Maintainer edit: turn the onboarding follow-up into a layered docs structure for first-time setup, provider selection, troubleshooting, CLI reference, and source-level architecture. This keeps quick start focused while giving advanced users precise reference paths. * docs: render architecture flow with mermaid Maintainer edit: replace the ASCII architecture sketch with a GitHub-rendered Mermaid flowchart so the core runtime path is easier to scan in the PR and README docs. * docs: recommend model presets for model config Maintainer edit: make named modelPresets the primary model configuration path and expand fallback preset examples so string fallbacks are clearly preset names, not raw model IDs. * docs: document api base urls and langfuse setup Maintainer edit: explain when users need apiBase/base URL in quick start and provider docs, and add Langfuse tracing setup with troubleshooting links. * docs: use python module pip consistently Maintainer edit: keep install commands tied to the active Python interpreter by using python -m pip in the Azure optional dependency notes too. * docs: add non-technical getting started path Maintainer edit: add a wizard-first guide for users without terminal or JSON background, including a text TUI menu example and links from the main docs entrypoints. * docs: avoid hard-wrapped prose in user docs Maintainer edit: unwrap ordinary prose across user-facing documentation while preserving markdown structure, code blocks, tables, lists, and prompt/template files. * docs: keep desktop list continuations nested Maintainer edit: preserve list nesting after unwrapping prose in the desktop WebUI sync guide. * docs: add one-command installer Maintainer edit: add auditable macOS/Linux and Windows install scripts that install nanobot-ai and start the onboarding wizard, then document the commands in the main onboarding entrypoints. * docs: add installer dry run mode Maintainer edit: add --dry-run to the one-command installer scripts so users can preview Python detection, install source, pip command, and wizard behavior without changing their environment. * docs: clean installer error output Maintainer edit: make PowerShell installer failures print a concise Error: message instead of Write-Error call-site details. * docs: add provider setup cookbook Maintainer edit: add pasteable provider recipes for common hosted, local, fallback, runtime switching, and Langfuse setups, then link the cookbook from onboarding and troubleshooting entrypoints. * docs: address review feedback * docs: clarify reader paths * docs: explain terminal basics for beginners * docs: clarify wizard navigation * docs: avoid duplicate onboarding steps * docs: add setup status check * docs: explain status output * docs: remove provider recommendation wording * docs: explain status diagnostics * docs: reduce hard-wrapped guidance * docs: migrate config examples to presets * docs: clarify python command fallbacks * docs: improve installer failure recovery * docs: expand install troubleshooting * docs: cover installer download failures * docs: put stable install paths first * docs: add bundled webui quick path * docs: clarify provider-neutral setup * docs: clarify gateway setup for chat surfaces * docs: improve docs navigation paths * docs: add configuration quick jump * docs: clarify provider secret variables * chore: request PR review acknowledgement Empty commit: please read the PR review comments and reply on the PR to confirm that you have received them. This commit intentionally changes no files; it exists only to notify the remote Codex run so it can end its active goal. * docs: add README start here guide * docs: avoid provider recommendation wording * docs: guide next steps after first reply * docs: explain merging JSON snippets * docs: add CLI command chooser * docs: add configuration task map * docs: add deployment readiness guide * docs: simplify WebUI entry paths * docs: add provider recipe chooser * docs: fix provider factual references Update OpenRouter and LongCat model examples, align Bedrock guidance, and make fallback snippets schema-valid. Also correct group policy wording and image-generation provider lists to match the current code. * fix: keep PowerShell installer from closing caller shell * docs: mention self-guided configuration
6.3 KiB
6.3 KiB
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 while those surfaces are in use |
| 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 nanobot gateway or nanobot serve.
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.
| Command | Description |
|---|---|
nanobot gateway |
Start the gateway 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 |
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.
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.