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 | nanoinfra --version | If this fails, try python -m nanoinfra --version |
| Create or refresh config | nanoinfra onboard | Creates ~/.nanoinfra/config.json and ~/.nanoinfra/workspaces/default/ |
| Refresh config non-interactively | nanoinfra onboard --refresh | Preserves existing values and adds missing default fields without prompting |
| Use guided setup | nanoinfra onboard --wizard | Best when you prefer prompts over hand-editing JSON |
| Open the browser workbench | nanoinfra webui | Prepares local WebUI settings, starts the gateway, and opens the browser |
| Check readiness without calling a model | nanoinfra status | Summarize the config and the workspace. Check the active provider and model configuration |
| Send one test message | nanoinfra agent -m "Hello!" | First proof that install, config, provider, model, and workspace all work |
| Chat in the terminal | nanoinfra agent | Interactive local chat. Exit with exit, /exit, :q, or Ctrl+D |
| Run the gateway directly | nanoinfra gateway | Service and operations command for the WebUI, chat apps, cron, and heartbeat |
| Deliver a local trigger | nanoinfra trigger <id> "message" | Create it first with /trigger <name> in the target chat session |
| Serve an OpenAI-compatible API | nanoinfra serve | Starts /v1/chat/completions, /v1/models, and /health |
| Check chat channel setup | nanoinfra channels status | Useful before starting nanoinfra gateway |
| Manage optional features | nanoinfra plugins list | Shows channels and optional capabilities you can turn on |
| Log in to a channel that uses a QR code or OAuth | nanoinfra channels login <channel> | Used by channels such as WhatsApp and Signal |
| Log in to OAuth model providers | nanoinfra provider login <provider> | Used by OpenAI Codex, xAI subscription, and GitHub Copilot providers |
| See what data connectors offer | nanoinfra connectors list | Shows each operation and its capability class |
| Authorise a data connector | nanoinfra connectors authorize <name> | One consent at a browser. Stores the refresh token |
Global
nanoinfra --help
nanoinfra --version
python -m nanoinfra --help
python -m nanoinfra --version
python -m nanoinfra ... is useful when the package is installed but the nanoinfra 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:
nanoinfra agent --config ./bot-a/config.json --workspace ./bot-a/workspace -m "Hello"
nanoinfra gateway --config ./bot-a/config.json --workspace ./bot-a/workspace
nanoinfra serve --config ./bot-a/config.json --workspace ./bot-a/workspace
Use --verbose on long-running processes when you need startup or runtime logs:
nanoinfra gateway --verbose
nanoinfra serve --verbose
Long-running commands keep working until you stop them. Press Ctrl+C in that terminal
to stop foreground nanoinfra gateway or nanoinfra serve. If you started the gateway
with --background, use nanoinfra gateway stop.
Setup
| Command | Description |
|---|---|
nanoinfra onboard | Initialize or refresh the default config and workspace |
nanoinfra onboard --refresh | Refresh an existing config without prompting, preserving existing values |
nanoinfra onboard --wizard | Use the interactive setup wizard |
nanoinfra onboard --config <path> --workspace <path> | Initialize or refresh a specific instance |
Default paths:
| Path | Default |
|---|---|
| Config | ~/.nanoinfra/config.json |
| Workspace | ~/.nanoinfra/workspaces/default/ |
Status
nanoinfra status
Shows the config path, the workspace path, the active model and a provider summary. It sends no model request.
| Command | Description |
|---|---|
nanoinfra status | Summarize the default config and the default workspace. Check that the Agent provider and model are ready |
nanoinfra status --config <path> | Check a specific config file |
nanoinfra status --workspace <path> | Show status with a workspace override |
nanoinfra status --config <path> --workspace <path> | Check a specific config with a workspace override |
On success, run the printed nanoinfra agent -m "Hello!" command to verify network access
and credentials. On failure, follow the printed WebUI Settings → Models or
nanoinfra onboard --wizard route.
Agent CLI
| Command | Description |
|---|---|
nanoinfra agent -m "Hello!" | Send one message and exit |
nanoinfra agent | Start interactive terminal chat |
nanoinfra agent --session <id> | Use a specific session key |
nanoinfra agent --workspace <path> | Override workspace |
nanoinfra agent --config <path> | Use a specific config file |
nanoinfra agent --no-markdown | Print plain text instead of Rich-rendered Markdown |
nanoinfra 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 |
|---|---|
nanoinfra webui | Create the config file and the workspace if they do not exist. Enable the local WebUI channel after you confirm. Start the gateway. Open http://127.0.0.1:8765 |
nanoinfra webui --background | Start or reuse a background gateway, then open the WebUI |
nanoinfra webui --no-open | Prepare and start the WebUI without opening a browser |
nanoinfra webui --port <port> | Set the port the WebUI and the WebSocket channel listen on |
nanoinfra webui --gateway-port <port> | Override the gateway health port |
nanoinfra webui --yes | Apply safe localhost WebUI defaults without confirmation. Configure provider credentials in Settings → Models |
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
nanoinfra gateway starts enabled chat channels, the WebUI and the WebSocket channel when they are configured, cron-backed system jobs, Dream, heartbeat, and the health endpoint. Most local browser users should start with nanoinfra 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 or Linux process that you can manage from the CLI.
| Command | Description |
|---|---|
nanoinfra gateway | Start the gateway in the foreground with config defaults |
nanoinfra gateway --verbose | Show verbose runtime output |
nanoinfra gateway --port <port> | Override gateway.port for the health endpoint |
nanoinfra gateway --workspace <path> | Override workspace |
nanoinfra gateway --config <path> | Use a specific config file |
nanoinfra gateway --background | Start the gateway as a background process |
nanoinfra gateway status | Show the recorded background gateway PID, state file, and log file |
nanoinfra gateway logs --no-follow | Print recent background gateway logs and exit |
nanoinfra gateway logs | Follow background gateway logs |
nanoinfra gateway restart | Restart the recorded background gateway with the current config |
nanoinfra gateway stop | Stop the recorded background gateway |
nanoinfra gateway install-service | Install a systemd user service or macOS LaunchAgent |
nanoinfra gateway install-service --dry-run | Preview the generated service file and system commands |
nanoinfra gateway uninstall-service | Remove the installed system service |
For custom instances, pass the same selector flags to management commands:
nanoinfra gateway --background --config ./bot-a/config.json --workspace ./bot-a/workspace
nanoinfra gateway status --config ./bot-a/config.json --workspace ./bot-a/workspace
nanoinfra gateway stop --config ./bot-a/config.json --workspace ./bot-a/workspace
nanoinfra 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 and
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 WebSocket channel serves the bundled WebUI, usually on port 8765. The gateway health endpoint does not serve it.
Local Triggers
A trigger delivers one message into the chat session it is bound to. Create it with
/trigger <name> in that session, then fire it from anywhere that can run a command.
nanoinfra trigger trg_8K4P2Q9X "Deploy finished on web-01"
Use stdin when another local process generates the message:
generate-report | nanoinfra trigger trg_8K4P2Q9X
| Command | Description |
|---|---|
nanoinfra trigger <id> "message" | Deliver one message through a trigger |
nanoinfra trigger <id> | Read the message from stdin |
nanoinfra trigger --config <path> <id> "message" | Use the workspace from a specific config |
nanoinfra trigger --workspace <path> <id> "message" | Use a specific workspace |
Run one gateway consumer per workspace. This local queue is not a distributed multi-consumer queue.
Local Triggers covers the rest:
- The at-least-once delivery guarantee.
- What happens to a delivery whose turn fails.
- The run records under
<workspace>/triggers/runs. - How to fire one trigger over HTTP with its own key.
- Why a trigger cannot be rehearsed in advance.
OpenAI-Compatible API
| Command | Description |
|---|---|
nanoinfra serve | Start /v1/chat/completions, /v1/models, and /health |
nanoinfra serve --host <host> | Override API bind host |
nanoinfra serve --port <port> | Override API port |
nanoinfra serve --timeout <seconds> | Override per-request timeout |
nanoinfra serve --verbose | Show runtime logs |
nanoinfra serve --workspace <path> | Override workspace |
nanoinfra 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.
Channels
| Command | Description |
|---|---|
nanoinfra channels status | Show configured channel status |
nanoinfra channels status --config <path> | Show channel status for a specific config |
nanoinfra channels login <channel> | Run interactive login for supported channels |
nanoinfra channels login <channel> --force | Re-authenticate even if credentials already exist |
nanoinfra channels login <channel> --config <path> | Use a specific config file |
nanoinfra plugins list --config <path> | Show the enabled state of each plugin and channel for a specific config |
Examples:
nanoinfra channels login whatsapp
nanoinfra channels login signal
nanoinfra channels status
See channels.md for channel-specific setup.
Optional Features
Use these commands when you want nanoinfra to add or remove a built-in capability
without hand-editing JSON. nanoinfra plugins enable may install the support
package first. nanoinfra plugins disable applies to channels such as Telegram,
Matrix, or Slack. It keeps your saved settings and turns the channel off.
nanoinfra keeps the plugins command name for compatibility, but these entries are
nanoinfra runtime support packages, not the user-invokable tools shown in WebUI
Apps. You cannot attach them to a chat turn with @.
| Feature name | What it enables |
|---|---|
api | Dependencies required by the OpenAI-compatible nanoinfra serve process |
azure | Azure identity support for Azure-hosted models |
bedrock | AWS Bedrock model provider support |
langfuse | Langfuse tracing support for OpenAI-compatible providers |
olostep | Olostep web search provider support |
A channel name such as telegram or slack | The connector package and saved channel enablement |
| Command | Description |
|---|---|
nanoinfra plugins list | Show available channels and optional capabilities |
nanoinfra plugins enable <name> | Install missing support and enable the feature or channel |
nanoinfra plugins enable <name> --logs | Show package install logs while enabling |
nanoinfra plugins disable <channel> | Turn off a channel without deleting its saved settings |
nanoinfra plugins list --config <path> | Read a specific config file |
nanoinfra plugins enable <name> --config <path> | Update a specific config file |
nanoinfra plugins disable <channel> --config <path> | Turn off a channel in a specific config file |
The standard installation includes document and PDF reading. nanoinfra still
accepts the old nanoinfra plugins enable documents and nanoinfra plugins enable pdf commands as no-op compatibility aliases.
Data Connectors
A data connector reaches one data source, with a capability class per operation. These two commands are the whole CLI surface. You declare activation in config, because enabling a connector is what gives it a token and a class.
| Command | Description |
|---|---|
nanoinfra connectors list | Installed connectors, whether each is active, and every operation's capability class |
nanoinfra connectors list --config <path> | Read a specific config file |
nanoinfra connectors authorize <name> --client-id <id> | Consent at a browser and store the refresh token this connector acts with |
nanoinfra connectors authorize <name> --account <address> | Pre-fill the consent screen, useful on a domain with several accounts |
nanoinfra connectors authorize <name> --port <n> | Move the loopback redirect. The OAuth client has to list the same address |
nanoinfra connectors authorize <name> --no-browser | Print the URL and open nothing, for a remote shell |
nanoinfra connectors list
nanoinfra connectors authorize google-calendar \
--client-id 1234-abc.apps.googleusercontent.com \
--account you@example.com
The command prompts for the client secret rather than taking it as a flag, so it stays out of your shell history. The command stores two secrets and prints their ids with the config block to review — never either value. The connector acts as whoever completes the consent.
Provider OAuth
| Command | Description |
|---|---|
nanoinfra provider login openai-codex --set-main | Authenticate Codex and select its current default model |
nanoinfra provider login xai-grok --set-main | Authenticate an eligible X Premium / Grok subscription and select Grok 4.5. Hosted X Search is enabled for models that advertise support |
nanoinfra provider login github-copilot --set-main | Authenticate GitHub Copilot and select its current default model |
nanoinfra provider logout openai-codex | Remove OpenAI Codex OAuth state |
nanoinfra provider logout xai-grok --config <path> | Remove the selected nanoinfra instance's xAI OAuth state |
nanoinfra provider logout github-copilot | Remove GitHub Copilot OAuth state |
See providers.md for when OAuth providers need an explicit provider and model selection.
Useful First Checks
nanoinfra --version
nanoinfra status
nanoinfra agent -m "Hello!"
If these fail, use troubleshooting.md before debugging WebUI, chat apps, Docker, systemd, or SDK integrations.