CLI Reference — Talk to Your AI Agents from the Terminal

Built for the Developer on the Team

You're the developer the CEO just asked to "look into this AI thing." Or you're a technical founder who wants to integrate AI agents into your existing tools, CI/CD pipelines, and scripts. Either way, you want:

A clean CLI — not a bloated desktop app

Simple authentication — one API key, stored securely

Scriptable output — JSON mode for piping and parsing

Conversation persistence — pick up where you left off

RAG training from the terminal — ingest files and directories

No surprises — clear errors, predictable behavior

The CEO.ai CLI gives you all of this. If you can npm install, you can be talking to your AI agents in 30 seconds.

Not a developer? That's fine — you don't need the CLI to use CEO.ai. The web app handles everything through a visual interface. The CLI is a power-user tool for developers who prefer the terminal. If you have a developer on your team, send them this page.

Installation

Requirements

Node.js 16 or later
A CEO.ai account with an active subscription and API key

Install Globally

bash

npm install -g @ceo-ai/cli

This gives you the ceo command available system-wide.

Get Your API Key

1 Log in to the CEO.ai Dashboard
2 Navigate to API Keys
3 Click Create API Key (requires a paid subscription)
4 Select the agent you want this key to connect to
5 Copy the generated key — it's only shown once

Configure

Interactive setup:

bash

ceo configure

You'll be prompted for your API Key (sk_live_...) and Endpoint (defaults to https://ingestion.api.ceo.ai).

Inline setup (skip prompts):

bash

ceo configure --key sk_live_abc123 --endpoint https://ingestion.api.ceo.ai

Verify your configuration:

bash

ceo config:show  
  
Current Configuration:  
  
  Endpoint:  https://ingestion.api.ceo.ai  
  API Key:   sk_live_abc1••••••••def4

Your configuration is stored in ~/.ceo-ai/config.json with restricted file permissions (0600). Your key never leaves your machine unencrypted.

Configure Options

bash

# Set API key  
ceo configure --key sk_live_abc123  
  
# Set endpoint  
ceo configure --endpoint https://ingestion.api.ceo.ai  
  
# Set a custom command name (see "Personalize Your CLI" below)  
ceo configure --name jules  
  
# Set default conversation directory  
ceo configure --conversation-dir ~/my-chats  
  
# Combine flags  
ceo configure --key sk_live_abc123 --name jules --conversation-dir ~/my-chats

Flag	Description
-k, --key <apiKey>	API key (`sk_live_...`)
-e, --endpoint <url>	API endpoint URL
-n, --name <commandName>	Personalize the CLI command name
-d, --conversation-dir <path>	Default directory for conversation files

Commands

ceo prompt <text>

Send a prompt to your AI agent.

The fundamental command. Send any prompt to the agent associated with your API key. By default, RAG mode is enabled — meaning the agent will use any knowledge you've trained it with.

bash

# Basic — returns the presigned URL immediately  
ceo prompt "What was our Q4 revenue?"  
  
# Wait for the result (most common usage)  
ceo prompt "What was our Q4 revenue?" --poll  
  
# Save result to a file  
ceo prompt "What was our Q4 revenue?" --poll -o result.json  
  
# Disable RAG mode  
ceo prompt "What is 2+2?" --no-rag --poll  
  
# Raw JSON output (useful for piping)  
ceo prompt "What was our Q4 revenue?" --poll --json  
  
# Override API key for a single request  
ceo prompt "Hello" --key sk_live_different_key --poll  
  
# Custom polling settings  
ceo prompt "Complex query..." --poll --poll-interval 5000 --poll-timeout 300000

Flag	Description	Default
--poll	Wait for results instead of returning the presigned URL	false
--poll-interval <ms>	How often to check for results	2000
--poll-timeout <ms>	Maximum time to wait for results	120000
--no-rag	Disable RAG mode (RAG is enabled by default)	—
-o, --output <file>	Write results to a file (implies --poll)	—
-k, --key <apiKey>	Override the configured API key	—
--json	Output raw JSON	false

How it works:

1 Your prompt is submitted and a presigned URL is returned immediately
2 The agent processes your request (using RAG knowledge if enabled)
3 Results are written to the presigned URL when ready

With --poll, the CLI automatically checks the presigned URL repeatedly until results arrive.

Example Output

$ ceo prompt "Summarize our sales performance this quarter" --poll  
  
✓ Request submitted  
  Agent:     Sales Analyst  
  Model:     claude-sonnet-4-5  
  Credits:   20  
⠋ Waiting for results... (attempt 12)  
✓ Results received  
  
--- Response ---  
  
Based on the available data, here are the key highlights...

ceo chat <text>

Start or continue a conversation with your agent.

The chat command maintains full conversation context across multiple exchanges. Every message and response is saved to a local JSON file, and the full history is sent with each new message so the agent has complete context.

bash

# Start a new conversation (creates conversation.json)  
ceo chat "What was our Q4 revenue?"  
  
# Continue the same conversation  
ceo chat "How does that compare to Q3?" -c conversation.json  
  
# Start a named conversation  
ceo chat "Analyze our marketing spend" -c marketing-analysis.json  
  
# Continue it  
ceo chat "Break it down by channel" -c marketing-analysis.json

Flag	Description	Default
-c, --conversation <file>	Conversation filename	conversation.json
--no-rag	Disable RAG mode	—
--poll-interval <ms>	Polling interval	2000
--poll-timeout <ms>	Max wait time	120000
-k, --key <apiKey>	Override configured API key	—
--json	Output raw JSON	false

Key behavior:

• chat automatically polls for results (no --poll flag needed)
• Full message history is sent to the agent for context on every exchange
• The conversation file is updated after each exchange
• Files are stored in your configured conversation directory (default: current working directory)

Conversation file format:

json

{  
  "metadata": {  
    "agentId": "agent-abc-123",  
    "agentName": "Financial Analyst",  
    "model": "gpt-4",  
    "startedAt": "2025-02-14T18:30:00.000Z",  
    "totalCreditsUsed": 4500,  
    "exchangeCount": 3  
  },  
  "messages": [  
    {  
      "role": "user",  
      "content": "What was our Q4 revenue?",  
      "timestamp": "2025-02-14T18:30:00.000Z"  
    },  
    {  
      "role": "assistant",  
      "content": "Q4 revenue was $12.5M, representing a 15% increase...",  
      "credits": 1500  
    }  
  ]  
}

Conversation files are standard JSON — easy to parse, import, version control, or feed into other tools.

ceo conversations

List all conversation files.

bash

# List conversations in the default directory  
ceo conversations  
  
# List conversations in a specific directory  
ceo conversations --dir ~/my-chats

Example Output

Conversations in /home/user/chats:  
  
  conversation.json  
    Agent: Financial Analyst | Model: gpt-4 | Messages: 6  
    Started: 2025-02-14T18:30:00.000Z  
    Updated: 2025-02-14T18:35:00.000Z  
  
  marketing-analysis.json  
    Agent: Marketing Bot | Model: gpt-4 | Messages: 4  
    Started: 2025-02-14T19:00:00.000Z  
    Updated: 2025-02-14T19:10:00.000Z

ceo poll <url>

Poll an existing presigned URL for results.

Useful if you submitted a prompt without --poll and want to check for results later — or if you're building a two-step workflow where submission and retrieval happen in different processes.

bash

# Poll a presigned URL  
ceo poll "https://ceo-ai-api-output-results.s3.amazonaws.com/api-data/..."  
  
# Save to file  
ceo poll "https://..." -o result.json  
  
# Custom interval and timeout  
ceo poll "https://..." --interval 5000 --timeout 300000  
  
# Raw JSON output  
ceo poll "https://..." --json

Flag	Description	Default
--interval <ms>	How often to check	2000
--timeout <ms>	Maximum wait time	120000
-o, --output <file>	Write results to file	—
--json	Output raw JSON	false

RAG Training — Train Your Agents from the Terminal

Feed your agents files and entire directories from the command line. Every file is automatically chunked and categorized. Your agents become experts in your business data without opening a browser.

ceo addRag <filepath>

Add a single file as RAG memory to your agent.

The file is automatically chunked into digestible pieces and the category (code, documentation, data) is detected from the file extension.

bash

# Add a markdown file  
ceo addRag ./docs/README.md  
  
# Add a code file  
ceo addRag ./src/index.js  
  
# Override the auto-detected category  
ceo addRag ./notes.txt --category documentation  
  
# Custom chunk size  
ceo addRag ./large-doc.md --chunk-size 4000  
  
# JSON output  
ceo addRag ./README.md --json

Category	Extensions
Code	.js .ts .jsx .tsx .py .java .go .rs .rb .php .c .cpp .h .cs .swift .kt .sql .sh .bash .yaml .yml .json .xml .html .css .scss
Documentation	.md .mdx .txt .rst .adoc .pdf .doc .docx
Data	.csv .tsv .log

Maximum file size is 4MB. For larger files, split them manually or use addRagDir with smaller individual files.

ceo addRagDir <dirpath>

Add all supported files from a directory as RAG memory.

This is the power command for bulk knowledge ingestion. Point it at a folder and every supported file gets processed, chunked, and added to your agent's memory. Use --recursive to include subdirectories.

bash

# Add all supported files from a directory  
ceo addRagDir ./docs  
  
# Include subdirectories (the most common usage)  
ceo addRagDir ./src --recursive  
  
# Only specific file types  
ceo addRagDir ./project --extensions md,txt,py --recursive  
  
# Override category for all files  
ceo addRagDir ./code-samples --category code  
  
# Custom chunk size for all files  
ceo addRagDir ./docs --chunk-size 4000 --recursive

Example Output

Found 5 files to add:  
  
  README.md  
  guide/getting-started.md  
  guide/advanced.md  
  api/endpoints.md  
  api/authentication.md  
  
✓ README.md (3 chunks, 450 credits)  
✓ guide/getting-started.md (5 chunks, 780 credits)  
✓ guide/advanced.md (8 chunks, 1200 credits)  
✓ api/endpoints.md (4 chunks, 620 credits)  
✓ api/authentication.md (2 chunks, 310 credits)  
  
--- Summary ---  
  
  Succeeded: 5  
  Credits:   3360

Hidden directories (.git, .env, etc.) and node_modules are automatically skipped when using --recursive. Empty files and files larger than 4MB are also skipped.

RAG Training — Practical Patterns

Train an agent on your entire codebase:

bash

ceo addRagDir ./src --recursive --extensions js,ts,json

Your agent now understands your code structure, patterns, and conventions.

Train an agent on your company documentation:

bash

ceo addRagDir ./docs --recursive --extensions md,txt,pdf

Your agent now knows your processes, policies, and product details.

Train an architect agent on your API docs + infrastructure:

bash

ceo addRagDir ./api-docs --recursive  
ceo addRag ./terraform/main.tf  
ceo addRag ./docker-compose.yml

Your architect now understands your API contracts and deployment patterns.

Train a support agent on your knowledge base:

bash

ceo addRagDir ./knowledge-base --recursive --extensions md,txt  
ceo addRagDir ./faq --recursive

Your support agent can now answer questions using your actual documentation.

Personalize Your CLI

Custom Command Name

Don't want to type ceo every time? Set a custom command name:

bash

# Set your preferred name  
ceo configure --name jules  
  
# Get shell alias instructions  
ceo alias:setup

Output

Add this line to your shell config:  
  
  alias jules='/usr/local/bin/ceo'  
  
  Or run this to add it automatically:  
  
  echo "alias jules='/usr/local/bin/ceo'" >> ~/.bashrc && source ~/.bashrc

After setting up the alias, use your custom name everywhere:

bash

jules chat "Good morning, what's on my agenda?"  
jules conversations  
jules prompt "Generate a report" --poll  
jules addRag ./new-docs/guide.md  
jules config:show

The command name must be a single word containing only letters and numbers.

Common Workflow Patterns

The CLI is scriptable by design. Here are patterns for integrating it into your development workflow.

Two-Step Workflow (Submit Now, Retrieve Later)

When to use: Long-running analysis, batch processing, or when you want to submit a task and come back to it.

bash

# Step 1: Submit prompt, get presigned URL  
$ ceo prompt "Long running analysis..."  
  
✓ Request submitted  
  Agent:     Data Analyst  
  Model:     claude-sonnet-4-5  
  Credits:   50  
  
  Presigned URL:  
  https://ceo-ai-api-output-results.s3.amazonaws.com/api-data/abc/def/1234.json?X-Amz-...  
  
  Use --poll to wait for results, or fetch the URL when ready.  
  
# Step 2: Later, poll for results  
$ ceo poll "https://ceo-ai-api-output-results.s3.amazonaws.com/..."  
  
✓ Results received  
  
--- Response ---  
  
Analysis complete...

Pipe JSON Output

When to use: Integrating agent responses into scripts, CI/CD pipelines, or data processing chains.

bash

# Pipe to jq for processing  
ceo prompt "List all customers" --poll --json | jq '.response.customers'  
  
# Pipe to another command  
ceo prompt "Get metrics" --poll --json > metrics.json  
  
# Use in shell scripts  
REVENUE=$(ceo prompt "What was Q4 revenue?" --poll --json | jq -r '.response.answer')  
echo "Q4 Revenue: $REVENUE"

Environment Variable Override

When to use: CI/CD pipelines, Docker containers, environments where you don't want to store config files.

bash

# Provide API key via environment variable  
CEO_API_KEY=sk_live_abc123 ceo prompt "Hello" --poll

Batch RAG Training in CI/CD

When to use: Keep your agents' knowledge current by training them as part of your deployment process.

bash

# In your deployment script or CI pipeline:  
# Train your agent on the latest docs after every deploy  
  
echo "Training agent on latest documentation..."  
ceo addRagDir ./docs --recursive --extensions md,txt  
ceo addRagDir ./api-reference --recursive --extensions md,json,yaml  
echo "Agent knowledge updated."

Automated Report Generation

When to use: Scheduled tasks, automated reporting, monitoring — anything you'd run on a cron schedule.

bash

#!/bin/bash  
# daily-report.sh — run via cron at 7am  
  
DATE=$(date +%Y-%m-%d)  
ceo prompt "Generate the daily operations report for ${DATE}" \  
  --poll \  
  -o "reports/daily-${DATE}.json"  
  
echo "Daily report generated: reports/daily-${DATE}.json"

Error Messages — Clear, Actionable, No Guessing

The CLI provides specific error messages so you know exactly what went wrong and how to fix it.

Common Errors

# No API key configured  
$ ceo prompt "Hello"  
Error: No API key configured. Run: ceo configure  
  
# Invalid API key  
$ ceo prompt "Hello" --key invalid_key  
Error: Invalid API key format  
  
# Insufficient credits  
$ ceo prompt "Hello" --poll  
✗ Request failed  
  Error: You need 50 credits but only have 20 available.  
  Details: {"requiredCredits":50,"availableCredits":20,"deficit":30}  
  
# Polling timeout  
$ ceo prompt "Hello" --poll --poll-timeout 5000  
✗ Polling failed  
  Error: Polling timed out after 5000ms (3 attempts)

Common Errors and Fixes

Error	Cause	Fix
No API key configured	No key in config file	Run `ceo configure --key sk_live_...`
Invalid API key format	Key doesn't match expected pattern	Check your key starts with `sk_live_`
Insufficient credits	Not enough credits	Add credits or wait for monthly refresh
Polling timed out	Agent took too long	Increase `--poll-timeout` (e.g., `300000` for 5 min)
File too large (max 4MB)	RAG file exceeds limit	Split the file or use `addRagDir` with smaller files

Uninstall

bash

npm uninstall -g @ceo-ai/cli  
  
# Optionally remove config  
rm -rf ~/.ceo-ai

Quick Reference

Command	Description
ceo configure	Set API key, endpoint, and preferences
ceo config:show	Display current configuration
ceo prompt <text>	Send a prompt to your agent
ceo chat <text>	Start or continue a conversation
ceo conversations	List all saved conversations
ceo poll <url>	Poll a presigned URL for results
ceo addRag <filepath>	Add a file as RAG memory to your agent
ceo addRagDir <dirpath>	Add all supported files from a directory as RAG memory
ceo alias:setup	Get instructions for setting up a custom command alias

Global Flags (Available on Most Commands)

Flag	Description
-k, --key <apiKey>	Override the configured API key for this request
-e, --endpoint <url>	Override the configured endpoint for this request
--json	Output raw JSON (useful for piping and scripting)

The CLI Is One Way In. Here's the Full Picture.

The CLI gives developers terminal access to the same agent platform that powers CEO.ai's web app. Everything you do in the CLI — prompts, conversations, RAG training — works with the same agents and the same knowledge as the web interface and the SDK.

If you want to…	Use…
Talk to agents from the terminal	CLI ← you are here
Embed agents in your Node.js applications	SDK
Build and manage agents visually	Web App — Agent Builder
Train agents on knowledge via web form	Web App — Add Memories
One-shot entire projects	CEO Agent
Automate multi-step operations	Workflows

View the SDK Documentation View the Agent Builder Get Your API Key

Ready to Build?

Install the CLI in 10 seconds. Configure your API key in 10 more. Start talking to your AI agents immediately.

bash

npm install -g @ceo-ai/cli && ceo configure

Don't have a CEO.ai account yet? Every plan includes Agent API access and CLI support. The developer on your team will thank you.

Get Started — See Plans Book a Setup Call

Talk to Your AI Agents from the Terminal.

Built for the Developer on the Team

Installation

Requirements

Install Globally

Get Your API Key

Configure

Configure Options

Commands

How it works:

Key behavior:

RAG Training — Train Your Agents from the Terminal

RAG Training — Practical Patterns

Personalize Your CLI

Custom Command Name

Common Workflow Patterns

Two-Step Workflow (Submit Now, Retrieve Later)

Pipe JSON Output

Environment Variable Override

Batch RAG Training in CI/CD

Automated Report Generation

Error Messages — Clear, Actionable, No Guessing

Common Errors and Fixes

Uninstall

Quick Reference

Global Flags (Available on Most Commands)

The CLI Is One Way In. Here's the Full Picture.

Ready to Build?