Skip to main content

​
Introduction

The nanobot CLI provides a complete command-line interface for managing your personal AI assistant. The CLI supports interactive chat, background gateway services, channel management, and configuration.

​
Installation

Install nanobot via pip: 
pip install nanobot
Verify installation: 
nanobot --version

🐈 nanobot v0.1.4.post3

​
Quick Start

​
1. Initialize Configuration

Create the default configuration and workspace: 
nanobot onboard

​
2. Configure API Key

Edit ~/.nanobot/config.json and add your API key: 
{
  "providers": {
    "openrouter": {
      "api_key": "your-api-key-here"
    }
  }
}

​
3. Chat with the Agent

Single message: 
nanobot agent -m "Hello, what can you do?"
Interactive mode: 
nanobot agent

​
Command Structure

The CLI follows this pattern: 
nanobot [COMMAND] [OPTIONS]

​
Available Commands

agent

Interactive chat with the AI agent

gateway

Start the background gateway service

onboard

Initialize configuration and workspace

status

Show system status and configuration

channels

Manage chat channels (WhatsApp, Telegram, etc.)

provider

Authenticate with OAuth providers

​
Global Options

​
--version
flag
Display the nanobot version and exit
nanobot --version
​
--help
flag
Show help message for any command
nanobot --help
nanobot agent --help

​
Configuration Files

​
Config Location

  • Config file: ~/.nanobot/config.json
  • Workspace: ~/.nanobot/workspace/
  • History: ~/.nanobot/history/cli_history
  • Cron jobs: ~/.nanobot/cron/jobs.json

​
Workspace Structure

~/.nanobot/
├── config.json          # Main configuration
├── workspace/           # Agent workspace
│   ├── sessions/        # Chat sessions
│   └── memory/          # Agent memory
├── history/             # CLI history
├── cron/               # Scheduled jobs
└── bridge/             # WhatsApp bridge (if used)

​
Exit Codes

The CLI uses standard exit codes:
  • 0: Success
  • 1: Error (configuration, authentication, runtime)
  • 130: Interrupted by user (Ctrl+C)

​
Environment Variables

​
BRIDGE_TOKEN
string
Authentication token for WhatsApp bridge (optional)

​
Error Handling

​
Common Errors

No API key configured: 
[red]Error: No API key configured.[/red]
Set one in ~/.nanobot/config.json under providers section
Configuration not found: 
nanobot onboard  # Initialize configuration
npm not found (for channels): 
[red]npm not found. Please install Node.js >= 18.[/red]

​
Interactive Mode

In interactive mode, the CLI provides:
  • Multiline paste (bracketed paste mode)
  • Command history (up/down arrows)
  • Tab completion (context-aware)
  • Clean display (no terminal artifacts)

​
Exit Commands

Any of these commands will exit interactive mode:
  • exit
  • quit
  • /exit
  • /quit
  • :q
  • Ctrl+C
  • Ctrl+D

​
Signal Handling

The CLI handles these signals gracefully:
  • SIGINT (Ctrl+C): Clean shutdown
  • SIGTERM: Clean shutdown
  • SIGHUP: Clean shutdown
  • SIGPIPE: Ignored (prevents crash on broken pipes)

​
Logging

Enable debug logging for troubleshooting: 
nanobot agent --logs -m "Debug message"
For the gateway service: 
nanobot gateway --verbose

​
Next Steps

Agent Command

Learn about interactive chat and options

Gateway Service

Set up background service for channels

Configuration

Customize agent behavior and settings

Channels

Connect WhatsApp, Telegram, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us