Algobot CLI

A powerful command-line interface for Algolia Agent Studio. Build, test, and deploy AI agents from your terminal with two modes: an interactive Terminal UI (TUI) for development and CLI commands for automation.

# Install
npm install -g algobot-ai

# Try the demo agent (no setup required)
algobot
> Find wireless headphones under $100
> What's your return policy?

# Or use CLI commands
algobot ask "What is Agent Studio?"
algobot agents list
algobot --profile prod agents publish <agent-id>

Two Ways to Work

🎨 Interactive TUI Mode - Full-screen terminal interface for development

• Real-time streaming responses with token-by-token display
• Slash commands (/model, /config, /temperature)
• Visual tool execution with 🔎 server-side and ⚡ client-side indicators
• Live context monitoring and auto-compaction
• Perfect for: Testing agents, debugging, interactive development

⚡ CLI Mode - Direct commands for scripting and automation

• Manage agents: create, list, patch, delete, publish
• Profile management across dev/staging/prod environments
• History search and analytics with --jq filtering
• Perfect for: CI/CD pipelines, bulk operations, scripts

# TUI Mode - Interactive development
algobot                              # Launch full TUI
> /model                             # Switch models interactively
> /config                            # Edit agent in $EDITOR
> Find wireless headphones under $100

# CLI Mode - Automation and scripting
algobot agents list --jq '.[] | .name'
algobot --env prod agents publish $AGENT_ID
algobot history search "error" --limit 10

Table of Contents

• Documentation & Guides
• Features
• Quick Start
• Commands
  • Slash Commands (TUI)
  • CLI Commands
• Advanced Features
• API Mapping
• Security
• Development
• What's New
• Learn More

📚 Documentation & Guides

New to Algobot CLI? Start here:

→ Getting Started Guide ⭐

Go from installation to a fully working agent with search capabilities. Perfect for first-time users.

→ Browse All Guides

17 comprehensive guides covering everything from basics to advanced topics:

• Interactive Testing - Master the TUI interface
• Agent Configuration - Models, temperature, tools
• Multi-Environment Management - Dev/staging/prod setup
• Debugging Agents - Systematic troubleshooting
• Automation & CI/CD - Pipeline integration
• Automated Testing - Integration & regression tests with --text
• Security Best Practices - Credential protection
• Conversation History - Search and track conversations
• Tool Usage Analytics - Monitor patterns
• ...and 8 more

Quick Reference:

• Slash Commands Reference - All TUI slash commands
• Keyboard Shortcuts - Complete cheat sheet
• Tools and Providers - Configuration guide

Features

Streaming AI, server-side tools, auto-compaction, GPT-5 parameters.

Streaming Completions (/1/agents/{id}/completions)

Real-time token-by-token streaming with SSE, graceful cancellation (Ctrl+C), and abort signal support.

algobot ask "Find wireless headphones under $200"
# Watch responses stream live, cancel anytime

Server-Side Tool Execution (Built-in Tools)

Tools like algolia_search_index execute on the backend, results stream back.

# AI decides to use algolia_search_index automatically
🔎 algolia_search_index
  index: instant_search
  query: wireless headphones

[AI synthesizes results into natural language response]

Auto-Compaction (/1/agents/{id}/compaction) ⚠️ Experimental

When context fills, automatically summarize conversation history. Note: May not be available on all environments yet.

# Conversation approaching token limit
📦 Compacting 50 messages into summary...
✅ Context freed: 45k → 8k tokens

GPT-5 Advanced Parameters

Interactive controls for reasoning effort and text verbosity.

/reasoning high        # Deeper chain-of-thought
/verbosity low         # Concise responses
/temperature 0.7       # Creativity control

Agent Lifecycle Management (/1/agents/*)

Create, list, patch, delete, publish/unpublish. Edit agent config in $EDITOR. Watch and auto-apply patch files.

algobot agents list
algobot agents create --name "Support Bot" --model gpt-4o
algobot /config                 # Edit agent in vim/vscode (like kubectl edit)
algobot agents watch patch.json # Live reload: edit file → auto-patch agent

Config-as-Code (v2.0.0)

Version-control agent definitions with mustache templates. Deploy repeatable agents across events, teams, or environments.

# Scaffold from an existing agent
algobot agents scaffold <agent-id>           # Generates agent-config.json + PROMPT.md

# Preview what would happen (no network mutations)
algobot --dry-run agents create --var event=Spring

# Deploy with template variables
algobot agents create --config agent-config.json --var event_name="Spring 2026" --var event_id="spring-2026"

# Update + publish in one step
algobot agents update <id> --config agent-config.json --var event_name="Summer 2026" --publish

Key features:

• --config auto-detects agent-config.json in cwd
• --var key=value resolves {{key}} placeholders (JSON-safe for config, raw for instructions)
• --dry-run is a global flag with an API-layer kill switch — mutations are blocked by construction
• Instructions loaded from .md files referenced in config (e.g., "instructions": "PROMPT.md")
• CLI flags (--name, --model) override config file values

Provider Management (/1/providers/*)

Manage LLM provider credentials, switch providers mid-conversation.

algobot providers create --name openai-prod
algobot /provider      # Interactive provider switcher

Multi-Environment Workflow

Switch between dev, staging, prod with profile-based config.

algobot --env dev agents list       # Development agents
algobot --env prod ask "hello"      # Production deployment

Client-Side Tools (exec, file_read, web_fetch)

Execute local tools with security confirmations, results sent for synthesis.

# AI can read files, execute commands (with permission)
⚡ exec
  command: ls -la
✓ result: [directory listing]

[AI interprets results]

Quick Start

# Install
npm install -g algobot-ai

# Try the demo agent (no setup required!)
algobot
> Find wireless headphones under $100
> What's your return policy?

# Ready for your own agent?
algobot init                         # Interactive setup wizard

Demo agent included: 60 queries/hour, searches e-commerce products, docs, CIA factbook.

Next steps: See the Getting Started Guide (15 minutes) for a complete walkthrough.

Commands

Slash Commands (Interactive Mode)

/config            # Edit agent config in $EDITOR (name, model, instructions, tools)
/model             # Interactive model selector (provider-aware)
/provider          # Switch LLM provider
/temperature       # Adjust creativity (0.0 → 2.0)
/reasoning         # Set reasoning effort: minimal|low|medium|high (GPT-5+)
/verbosity         # Set text length: low|medium|high (GPT-5+)
/compact           # Summarize conversation to free context
/tools             # Show agent's available tools
/context           # View token usage and context stats
/verbose           # Toggle HTTP request/response logging
/search <query>    # Fuzzy search conversation history
/conversations     # List recent conversations
/conversations search <q>  # Search conversations by title
/conversation <id> # Load conversation context (with auto-compaction)
/reset             # Clear conversation context
/help              # Full command list

CLI Commands

# Getting started
algobot                              # Start interactive TUI
algobot init                         # Interactive wizard to create first agent
algobot version                      # Show version

# Agent management
algobot agents list
algobot agents create --name "My Bot" --model gpt-4o
algobot agents get <agent-id>
algobot agents edit                  # Edit agent in $EDITOR (CLI version of /config)
algobot agents publish <agent-id>
algobot agents unpublish <agent-id>
algobot agents delete <agent-id>
algobot agents export <agent-id>     # Export agent config to JSON
algobot agents copy <id> --from-env dev --to-env prod
algobot agents patch <agent-id> --file config.json
algobot agents watch patch.json      # Watch file and auto-apply patches on changes

# Config-as-code (v2.0.0)
algobot agents scaffold <agent-id>   # Generate agent-config.json + PROMPT.md
algobot agents create --config agent-config.json --var event="Spring 2026"
algobot agents update <id> --config agent-config.json --var event="Summer" --publish
algobot --dry-run agents create ...  # Preview resolved config (no network mutations)

# Provider management
algobot providers list
algobot providers create --name openai-prod
algobot providers get <provider-id>
algobot providers patch <provider-id> --file provider.json
algobot providers delete <provider-id>

# Profile management (AWS CLI-style)
algobot profiles list
algobot profiles add --name dev --env dev
algobot profiles show [name]         # Show profile details as JSON
algobot profiles setdefault prod
algobot profiles remove <name>
algobot --profile staging ask "hello"

# Tool management
algobot tools list
algobot tools add --tool-file searchtool.json
algobot tools remove <toolType>

# History & search
algobot history search "deployment"
algobot history recent --short       # Git-like compact format
algobot history stats
algobot history interactive          # Ctrl+R-style fuzzy search
algobot history clear

# Conversation management
algobot conversations list           # List recent conversations
algobot conversations list --short   # Git-like compact format
algobot conversations get <id>       # Get conversation with messages
algobot conversations search <query> # Search by title
algobot conversations export         # Export to JSON file
algobot conversations delete <id>    # Delete a conversation

# Permissions & security
algobot permissions list
algobot permissions init             # Initialize default config
algobot permissions add /safe/directory
algobot permissions test --command "cat /etc/passwd"
algobot permissions logs

# Global flags
algobot --env dev agents list        # Use specific environment
algobot --verbose ask "hello"        # Show HTTP requests/responses
algobot --dry-run agents create ...  # Preview without executing
algobot --jq '.name' agents list     # Pipe JSON through jq
algobot --confirm ask "run tests"    # Skip exec confirmations

Advanced

Conversation Auto-Compaction ⚠️ Experimental

Triggers compaction API at 80% context window. Preserves continuity. Note: May not be available on all environments yet.

Provider-Aware Model Validation

Only shows valid models for current provider in /model selector.

Reasoning Model Detection

o1, o3, gpt-5: disables temperature, enables reasoning effort controls.

Tool Call Visualization

Server-side (🔎) vs client-side (⚡) with visual hierarchy.

Verbose Mode

Full HTTP logs with URLs, headers, bodies. Multi-environment debugging.

/verbose
# Now see:
━━━ HTTP Request ━━━
PATCH https://conversational-ai-dev.algolia.com/1/agents/abc123
X-Algolia-Application-Id: MYAPP
Body: {"model": "gpt-5-nano"}
━━━ HTTP Response ━━━
Status: 200 OK

API Mapping

| Feature | Agent Studio API | Implementation | | ----------------- | -------------------------------- | -------------------------------------------------------------------------------------- | | Streaming | SSE with ai-sdk-5 format | Token-by-token display, graceful abort | | Compaction ⚠️ | /1/agents/{id}/compaction | Auto-triggered at 80% context (experimental, may not be available on all environments) | | Server Tools | Tools in agent config | Rich visualization, no synthesis needed | | Client Tools | Same protocol | Local execution, security confirmations | | GPT-5 Params | reasoning.effort, text.verbosity | Interactive selectors, cycle shortcuts | | Environments | Separate dev/staging/prod | Profile system, easy switching | | Agent Editing | PATCH /1/agents/{id} | Unix-style $EDITOR integration | | Conversations | /1/agents/{id}/conversations | List, search, load context, delete |

Security

Encrypted Credentials

AES-256-GCM in ~/.algobot-profiles (mode 0600).

Filesystem Permissions

Prevents tools from accessing restricted directories.

algobot permissions add /safe/directory
algobot permissions remove /unsafe/path

Execution Confirmations

exec requires confirmation unless --confirm flag.

Development

git clone <repository>
cd demos/algobot-cli
npm install
npm test              # 598 tests
npm run lint
npm link              # Install globally

Architecture

src/
├── cli.js              # Commander entry
├── tui/                # Ink UI (2400+ lines)
├── commands/           # Agent/provider/tool commands
├── ai-communication.js # Streaming with SSE
├── compact-api.js      # Auto-compaction
├── agent-api.js        # REST client (with dry-run kill switch)
├── template.js         # Mustache template engine for config-as-code
├── profile-store.js    # Multi-profile management
└── history/            # JSONL + fuzzy search

Learn More

• Agent Studio Docs
• API: /1/agents/{id}/completions, /1/agents/{id}/compaction, /1/providers

What's New in v1.0.0

Complete TUI Rewrite

• Ink-based terminal UI (2400+ lines)
• Custom input system with full keyboard support
• Multiline editing with vim-like navigation (Ctrl+A/E, Alt+D, etc.)
• Enter to send, Shift+Enter for newlines

Interactive UI

• /model - Provider-aware model selector with arrow key navigation
• /temperature - Labeled preset selector (Precise/Balanced/Creative)
• /reasoning - Effort selector for o1/o3/gpt-5 models (minimal/low/medium/high)
• /verbosity - Text length control for GPT-5+ (low/medium/high)
• Slash command autocomplete with vertical dropdown
• Interactive search navigator with tool parameter hints
• Modal system for selectors and confirmations

Configuration Management

• /config - Edit agent in $EDITOR (vim/vscode) with change detection and diff display
• Unix-style workflow (like kubectl edit, git config --edit)
• Auto-validation on save with retry prompts

Tool System

• Fixed server-side tool synthesis bug (no more "No tool output found")
• Tool display: input → tool calls → results → response (chronological flow)
• Autocomplete with parameter hints
• Visual distinction: 🔎 server-side, ⚡ client-side

History & Search

• Persistent command history across sessions
• Interactive search with Ctrl+R-style fuzzy finder
• Git-like compact format (history recent --short)
• --jq flag for JSON filtering

Compaction ⚠️ Experimental

• /compact - Manual conversation summarization (may not be available on all environments)
• /context - Token usage and context stats
• Auto-compaction at 80% context window

Verbose Mode

• Full HTTP request/response logging with visual separators
• Shows URLs, headers, request bodies for all API calls
• Essential for multi-environment debugging

Other

• Rainbow chase thinking animation
• Message/tool counters in status bar
• Visual context display with timezone
• Shortcuts reveal UI (? for help)
• Exit fix: double Ctrl+C now cleanly returns to shell

Foundation (v0.6-v0.7)

• Multi-profile system (AWS CLI-style)
• Multi-environment support (local/dev/staging/prod)
• Provider management with secure credential storage

What's New in v1.2.0

Conversation Management

• algobot conversations list - List, search, export, delete conversations
• /conversations - Browse recent conversations in TUI
• /conversation <id> - Load previous conversation into current context with auto-compaction
• Transparent compression: see original vs. summarized token counts

What's New in v2.0.0

Config-as-Code

• agents scaffold — generate agent-config.json + PROMPT.md from existing agents
• agents create --config — deploy from version-controlled config files
• agents update --config — update with config files, inline JSON, or CLI flags
• Mustache templates ({{variable}}) with --var key=value for repeatable deployments
• --dry-run global flag with API-layer kill switch — mutations blocked by construction
• --publish flag on update — update + publish in one step
• Smart merge: CLI flags override config file values
• JSON-safe template rendering (quotes/backslashes handled automatically)

Quality

• 598 tests passing (up from 488 in v1.0.0)
• Fixed --dry-run parsing (was silently broken — Commander global option conflict)
• Fixed "deleteed" typo in agent delete output

Built to showcase Agent Studio.