Skip to main content

Usage

nanobot agent [OPTIONS]

Description

The agent command provides direct interaction with the nanobot AI assistant. It supports both single-message mode (for scripts and quick queries) and interactive mode (for ongoing conversations).

Modes

Single Message Mode

Send a single message and get a response:
nanobot agent -m "What's the weather like?"
Output:
🐈 nanobot

I don't have access to real-time weather data. To check the weather, 
you can use a weather service or ask me to search for it.

Interactive Mode

Start a persistent conversation (default when no message is provided):
nanobot agent
Output:
🐈 Interactive mode (type exit or Ctrl+C to quit)

You: Hello!

🐈 nanobot

Hello! How can I assist you today?

You: _

Options

--message
string
Message to send to the agent. If provided, runs in single-message mode.
nanobot agent -m "Explain quantum computing"
Required: No
Default: None (starts interactive mode)
--session
string
Session ID for conversation context. Sessions maintain chat history and context across multiple invocations.
nanobot agent -s "project-review" -m "Continue our discussion"
Required: No
Default: "cli:direct"
Format: channel:chat_id or simple identifier
--markdown
boolean
Render assistant responses as formatted Markdown.
# Disable markdown rendering
nanobot agent --no-markdown -m "List three items"
Required: No
Default: true
Toggle: Use --markdown or --no-markdown
--logs
boolean
Show detailed runtime logs during agent execution. Useful for debugging tool usage, API calls, and internal operations.
nanobot agent --logs -m "Search for Python tutorials"
Required: No
Default: false
Toggle: Use --logs or --no-logs

Examples

Quick Question

nanobot agent -m "What's 15% of 240?"

Code Generation

nanobot agent -m "Write a Python function to calculate fibonacci numbers"

Multi-Turn Conversation

nanobot agent -s "code-review"
Then:
You: Review the main.py file
You: What are the performance issues?
You: How can I optimize it?
You: exit

With Debug Logs

nanobot agent --logs -m "Search for latest Python releases"
Output includes:
  ↳ Using tool: web_search
  ↳ Query: "latest Python releases 2024"
  ↳ Found 5 results

🐈 nanobot

The latest Python releases include...

Plain Text Output

nanobot agent --no-markdown -m "Hello" > output.txt

Interactive Mode Features

Command History

Use arrow keys to navigate previous commands:
  • Up Arrow: Previous command
  • Down Arrow: Next command
History is saved to ~/.nanobot/history/cli_history

Multiline Paste

Paste multiple lines of text (code, documents) directly:
You: Here's the error I'm getting:
  File "main.py", line 42
    print("Hello"
         ^
SyntaxError: incomplete input
Bracketed paste mode automatically handles multiline input.

Exit Commands

Any of these will exit:
  • exit
  • quit
  • /exit
  • /quit
  • :q
  • Ctrl+C
  • Ctrl+D (EOF)

Progress Indicators

When --logs is disabled (default), a spinner shows the agent is thinking:
nanobot is thinking...
When --logs is enabled, you see detailed tool usage:
  ↳ Reading file: src/main.py
  ↳ Analyzing code structure
  ↳ Generating suggestions

Sessions

Sessions maintain conversation context, including:
  • Chat history
  • Agent memory
  • Tool state
  • User preferences

Session IDs

Format: channel:chat_id Examples:
  • cli:direct (default)
  • cli:project-alpha
  • telegram:123456
  • debugging

Persistent Sessions

Sessions are stored in ~/.nanobot/workspace/sessions/:
ls ~/.nanobot/workspace/sessions/
# cli_direct.json
# cli_project-alpha.json

Clear Session

To start fresh, delete the session file:
rm ~/.nanobot/workspace/sessions/cli_direct.json

Configuration

The agent command uses settings from ~/.nanobot/config.json:
{
  "agents": {
    "defaults": {
      "model": "openai/gpt-4",
      "temperature": 0.7,
      "max_tokens": 4096,
      "max_tool_iterations": 10,
      "memory_window": 20,
      "reasoning_effort": "medium"
    }
  }
}
See Configuration for all options.

Exit Codes

  • 0: Success
  • 1: Error (API key missing, network failure, etc.)
  • 130: Interrupted by user (Ctrl+C)

Error Handling

No API Key

[red]Error: No API key configured.[/red]
Set one in ~/.nanobot/config.json under providers section
Solution:
# Edit config
vim ~/.nanobot/config.json

# Add API key
{
  "providers": {
    "openrouter": {
      "api_key": "sk-..."
    }
  }
}

Model Not Available

[red]Error: Model not available: openai/gpt-5[/red]
Solution: Check available models in your provider dashboard.

Network Error

[red]Connection error: Unable to reach API endpoint[/red]
Solution: Check network connection and API status.

Terminal Requirements

Supported Terminals

  • Most modern terminals (iTerm2, Terminal.app, GNOME Terminal, etc.)
  • Supports ANSI color codes
  • UTF-8 encoding

Terminal Features Used

  • Bracketed paste mode: Multiline paste
  • ANSI colors: Formatted output
  • Spinner animation: Progress indicator
  • Rich formatting: Markdown rendering

Terminal Issues

Colors not working:
# Force color output
export FORCE_COLOR=1
nanobot agent -m "Hello"
Broken characters:
# Check encoding
echo $LANG  # Should be UTF-8

Performance Tips

Faster Responses

Use cheaper/faster models for simple queries:
{
  "agents": {
    "defaults": {
      "model": "openai/gpt-3.5-turbo"
    }
  }
}

Reduce Token Usage

Limit max tokens:
{
  "agents": {
    "defaults": {
      "max_tokens": 1024
    }
  }
}

Disable Tools

For simple chat without tool usage:
{
  "tools": {
    "restrict_to_workspace": true,
    "web": {
      "enabled": false
    }
  }
}

Integration with Scripts

Shell Script

#!/bin/bash

# Get response from agent
response=$(nanobot agent -m "Summarize: $1" --no-markdown)
echo "Summary: $response"

Python Script

import subprocess
import json

def ask_nanobot(question: str) -> str:
    result = subprocess.run(
        ["nanobot", "agent", "-m", question, "--no-markdown"],
        capture_output=True,
        text=True
    )
    return result.stdout.strip()

response = ask_nanobot("What is 2+2?")
print(response)
  • gateway - Run agent as background service
  • status - Check configuration and model
  • onboard - Initialize configuration

See Also

Build docs developers (and LLMs) love