@algolia/algobot-cli

v2.1.2

Published

3 days ago

A CLI REPL for chatting with Algolia Agents.

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 @algolia/algobot-cli
# or run it once without installing: npx @algolia/algobot-cli

# 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>

Formerly published as algobot-ai. The algobot command is unchanged.

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

📚 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

Region Support

Production Agent Studio has region-specific endpoints. Use --region eu|us to select one (default: eu). The flag works globally, and profiles add accepts --region (persisted in the profile).

algobot --env prod --region eu agents list   # https://agent-studio.eu.algolia.com (default)
algobot --env prod --region us agents list   # https://agent-studio.us.algolia.com
algobot profiles add --name us-prod --env prod --region us --app-id XXX --api-key YYY
algobot --profile us-prod agents list

Notes:

--env staging is EU-only for now: --region us with staging exits with an error.
dev and local are region-independent.
Precedence: --region flag > profile region > eu default.

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 @algolia/algobot-cli

# 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.

Point the demo at your own app: without a profile, the CLI uses an embedded public, search-only demo key. Environment variables override it:

export ALGOBOT_DEMO_APP_ID=YOUR_APP_ID
export ALGOBOT_DEMO_API_KEY=YOUR_SEARCH_ONLY_KEY
export ALGOBOT_DEMO_AGENT_ID=YOUR_PUBLISHED_AGENT_ID
algobot ask "hello"

Each variable falls back to the embedded value when unset.

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

# Agent Studio Evaluations (EXPERIMENTAL: undocumented endpoints, may change)
algobot evals metrics list
algobot evals metrics create --slug tone --name Tone --rubrics '{"criteria":"friendly"}'
algobot evals profiles build --index-name products          # then: evals profiles build-status <taskId>
algobot evals datasets list-cases <dataset-id> --status pending
algobot evals cases update <case-id> --status approved
algobot evals datasets finalize <dataset-id>
algobot evals experiments create --index-name products --agent-uuid <id> --metric-ids <m1,m2>
algobot evals experiments run <experiment-id>               # then: evals runs get <exp> <run>
algobot evals runs summary <experiment-id> <run-id>
algobot evals compare --run-a <runA> --run-b <runB>

# Global flags
algobot --env dev agents list        # Use specific environment
algobot --env prod --region us agents list  # Use US region (default: eu)
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

Agent Studio Evaluations ⚠️ Experimental

algobot evals gives terminal access to the Agent Studio Evaluations feature (metric catalog, profile snapshots, dataset generation, experiment runs, judgments, run comparison). The whole group is EXPERIMENTAL: the endpoints are undocumented, not in the public OpenAPI spec or the official SDK, and may change or disappear without notice.

Implemented against the backend rag/routers/v1/external_evals.py router (base path /1/evals/...), through the CLI's shared raw HTTP client, so auth headers, retry, verbose logging, --dry-run and --jq behave exactly like every other command.

Sub-groups (42 endpoints total, JSON output everywhere):

algobot evals profiles ...     # build (async) / build-status / list / get / delete for index + agent profiles
algobot evals metrics ...      # list / create / update / delete of the rubric catalog
algobot evals datasets ...     # create / list / get / delete / drift-check / refresh-profiles /
                               # generate (async) / build-status / list-cases / bulk-status /
                               # finalize / import
algobot evals cases ...        # update (expected answer key + review status)
algobot evals experiments ...  # create / list / get / proceed / cancel / retry / delete /
                               # run (async) / runs
algobot evals runs ...         # get / judgments / summary / case (per-case drilldown)
algobot evals judgments ...    # create (re-judge a stored completion) / list
algobot evals judge            # stateless: score one inline agent turn, nothing stored
algobot evals compare          # before/after comparison of two runs sharing a dataset

Notes:

Every command is non-interactive (flags only). JSON bodies are accepted inline (--rubrics '{"criteria":"friendly"}') or from a file: any JSON-valued flag takes a path to a JSON file (--rubrics rubric.json, --expected expected.json, --rows rows.json).
Long-running operations are asynchronous: start commands return a taskId/runId; poll with evals profiles build-status, evals datasets build-status, or evals runs get. No blocking loops.
Do not build production tooling on this group; treat it as internal dogfooding.

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 https://github.com/algolia/algobot-cli.git
cd algobot-cli
npm install
npm test
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

Contributing

Open issues and pull requests on algolia/algobot-cli. Before pushing, run npm run lint and npm test; CI runs the same checks on Node 20 and 22. Report security problems privately, see SECURITY.md.

Releasing

Releases go to npm with npm Trusted Publishing and staged publishing: no npm token is stored in the repository, and no version goes live without a maintainer approving it with 2FA.

Open a PR that bumps version in package.json and package-lock.json (npm version patch --no-git-tag-version) and adds a CHANGELOG.md entry.
Merge it to main.
Run Actions > Release > Run workflow on main. The workflow builds, lints and tests, refuses a version that is already on npm, and stages the package with npm stage publish. The job summary shows the stage id.
Approve the staged package with 2FA: on npmjs.com in the package's Staged Packages tab, or with npm stage approve <stage-id> (npm 11.15.0 or newer).
Run Actions > Tag release > Run workflow on main. It checks that the version is live on npm, then creates the v<version> tag and a GitHub release with generated notes.

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.1.0

Agent Studio Evaluations (experimental)

algobot evals — run Agent Studio Evaluations from the CLI: metric catalogs (faithfulness, relevance, tone, custom rubrics), datasets (generate from index profiles or import real conversations), experiments, runs, judgments, and run comparison
JSON-friendly output for scripting with the global --jq filter, poll-style status commands for async operations
Marked experimental: built on undocumented endpoints that may change without notice

Region support

--region eu|us global flag (default eu) to reach region-specific production endpoints (--env prod --region us → https://agent-studio.us.algolia.com)
Optional region persisted in profiles (profiles add --region us ...), shown as a column in profiles list
Precedence: --region flag > profile region > eu; staging is EU-only for now

Reliability & scripting

Unknown commands exit 1 with an error instead of silently becoming a chat message
Piped prompts are forwarded verbatim; conversations output is machine-readable when piped (no ANSI codes, pagination via --page)
agents scaffold output is re-creatable with agents create --config (deprecated fields stripped, providerId preserved)
Global --agent/--agent-id override is forwarded consistently across all command groups

Quality

695 tests passing (up from 598 in v2.0.0)
Test suite exits green on low-CPU CI runners (in-band jest process.exitCode leak fixed)

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)