CLI README

ceo-cli/README.md

@ceo-ai/cli

Command-line interface for the CEO.AI API. Send prompts to your AI agents, poll for results, and manage your configuration — all from the terminal.

Installation

npm install -g @ceo-ai/cli  

Quick Start

# 1. Configure your API key  
ceo configure --key sk_live_your_api_key_here  
  
# 2. Send a prompt and wait for the result  
ceo prompt "What was our Q4 revenue?" --poll  
  
# 3. That's it!  

Configuration

Interactive Setup

ceo configure  

You'll be prompted for:

• API Key — your sk_live_... key from the CEO.AI dashboard
• Endpoint — the API URL (defaults to https://ingestion.api.ceo.ai) (optional)

Inline Setup

ceo configure --key sk_live_abc123 

Per-Session Configuration (Environment Variables)

You can set a different API key for each terminal window using environment variables. This is useful when working with multiple agents or projects simultaneously.

Terminal A — Content Strategist:

export CEO_AI_API_KEY="sk_live_some_key"  
ceo chat "Create an editorial calendar for this week"  

Terminal B — Personal Knowledge & Procedures Retrieval Agent:

export CEO_AI_API_KEY="sk_live_some_key"  
ceo chat "Remind me, what are the steps to completing procedure XYZ?"  

View Current Config

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

Security Notes

• Config file — stored at ~/.ceo-ai/config.json with 0600 permissions (owner read/write only). The directory is created with 0700 permissions.

• Environment variables — the standard way to provide per-session credentials. Be aware of the following:

• Shell history: export CEO_AI_API_KEY="..." may be saved in your shell history. To avoid this, use one of these approaches:

    # Option A: Prefix with a space (bash/zsh ignore these in history)  
     export CEO_AI_API_KEY="sk_live_abc123"  
  
    # Option B: Read interactively (nothing displayed or logged)  
    read -s CEO_AI_API_KEY && export CEO_AI_API_KEY  
  
    # Option C: Source from a protected file  
    echo 'export CEO_AI_API_KEY="sk_live_abc123"' > ~/.ceo-ai/.env  
    chmod 600 ~/.ceo-ai/.env  
    source ~/.ceo-ai/.env  
    ```
  
  
- **Shared servers:** On multi-user systems, other users with elevated privileges could potentially inspect environment variables of running processes. On personal machines, this is not a concern.  
  
- **Displayed output** — API keys are always masked in CLI output (e.g., `sk_live_abc1••••••••def4`). Full keys are never printed or logged.  
  
- **`--key` flag** — using `--key` on the command line may also appear in shell history. Prefer environment variables or `ceo configure` for persistent setup.  
  
## Commands  
  
### `ceo prompt <text>`  
  
Send a prompt to your AI agent.  
  

```bash  
# Basic — returns the presigned URL immediately  
ceo prompt "What was our Q4 revenue?"  
  
# Wait for the result  
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  

Options:

| 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 | — |
| -e, --endpoint <url> | Override the configured endpoint | — |
| --json | Output raw JSON | false |

ceo chat <text>

Start or continue a conversation. Automatically polls for results and saves the exchange to a local JSON file.

# 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  
  
### `ceo poll <url>`  
  
Poll an existing presigned URL for results. Useful if you submitted a prompt earlier and want to check for results later.  
  

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

Options:

| 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 | — |
| -e, --endpoint <url> | Override configured endpoint | — |
| --json | Output raw JSON | false |

When you continue a conversation, the full message history is sent to the agent for context. The file is updated after each exchange.

Conversation file format:

{  
  "metadata": {  
    "agentId": "agent-abc-123",  
    "agentName": "Financial Analyst",  
    "model": "gpt-4",  
    "tenantId": "tenant-456",  
    "startedAt": "2025-02-14T18:30:00.000Z",  
    "lastUpdatedAt": "2025-02-14T18:35: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...",  
      "timestamp": "2025-02-14T18:30:15.000Z",  
      "credits": 1500  
    }  
  ]  
}  

ceo conversations

List all conversation files in your conversation directory.

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

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  

Options:

| Flag | Description | Default |
|------|-------------|---------|
| -d, --dir <path> | Directory to search | Configured dir or ./ |

ceo addRag <filepath>

Add a file as RAG memory to your agent. The file is automatically chunked and the category is detected from the file extension.

# 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  

Supported file types:

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

Options:

| Flag | Description | Default |
|------|-------------|---------|
| -c, --category <category> | Override auto-detected category (code, documentation, data, other) | Auto-detected |
| --chunk-size <size> | Maximum chunk size in characters | 2000 |
| -k, --key <apiKey> | Override configured API key | — |
| -e, --endpoint <url> | Override configured endpoint | — |
| --json | Output raw JSON response | false |

Note: 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. Each file is processed individually.

# Add all supported files from a directory  
ceo addRagDir ./docs  
  
# Include subdirectories  
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  

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  

Options:

| Flag | Description | Default |
|------|-------------|---------|
| -r, --recursive | Include subdirectories | false |
| --extensions <exts> | Comma-separated file extensions to include | md,txt,js,ts,py,json,yaml,yml,html,css,sql,sh,go,rs,rb,java,php,c,cpp,h |
| -c, --category <category> | Override auto-detected category for all files | Auto-detected per file |
| --chunk-size <size> | Maximum chunk size in characters | 2000 |
| -k, --key <apiKey> | Override configured API key | — |
| -e, --endpoint <url> | Override configured endpoint | — |
| --json | Output raw JSON response | false |

Directories named . (hidden) and node_modules are automatically skipped when using --recursive. Empty files and files larger than 4MB are also skipped.

ceo configure

Set your API key, endpoint, and preferences.

# Interactive setup  
ceo configure  
  
# Set API key  
ceo configure --key sk_live_abc123  
  
# Set endpoint  
ceo configure --endpoint https://injestion.api.ceo.ai  
  
# Set a custom command name  
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  

Options:

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

ceo config:show

Display the current configuration (API key is masked).

Examples

Basic Prompt and Poll

$ 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 alias:setup

After setting a custom command name with ceo configure --name, run this to get instructions for creating a shell alias.

ceo configure --name jules  
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, you can use your custom name everywhere:

jules chat "Good morning, what's on my agenda?"  
jules conversations  
jules configure --key sk_live_newkey  
jules config:show  

Save Results to File

$ ceo prompt "Generate a detailed financial report" --poll -o report.json  
✓ Request submitted  
✓ Results received  
  
✓ Results written to /Users/you/report.json  

Pipe JSON Output

# 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  

Two-Step Workflow

# 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/api-data/abc/def/1234.json?X-Amz-..."  
  
✓ Results received  
  
--- Response ---  
  
Analysis complete...  

Environment Variable Override

You can also provide your API key via an environment variable:

CEO_API_KEY=sk_live_abc123 ceo prompt "Hello" --poll  

Error Handling

The CLI provides clear error messages:

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

Conversations

The CLI supports persistent conversations that maintain full context across prompts.

Starting a Conversation

# Auto-named (conversation.json, conversation-1.json, etc.)  
ceo chat "What was our Q4 revenue?"  
  
# Named conversation  
ceo chat "Analyze our marketing spend" -c marketing.json  

Continuing a Conversation

# Picks up full history and sends it for context  
ceo chat "How does that compare to Q3?" -c conversation.json  

Using Conversations with prompt

The --conversation flag also works with the prompt command:

# Start with prompt command (auto-generates filename)  
ceo prompt "What was revenue?" --conversation  
  
# Or specify a file  
ceo prompt "What was revenue?" --conversation my-session.json  

Conversation Storage

• Files are stored in your configured conversation directory (default: current working directory)
• Set a default directory: ceo configure --conversation-dir ~/my-chats
• Each file contains full metadata (agent, model, credits used) and all messages
• Files are standard JSON — easy to parse, import, or version control

Managing Conversations

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

Custom Command Name

Personalize the CLI command to anything you want:

# Set your preferred name  
ceo configure --name jules  
  
# Get shell alias instructions  
ceo alias:setup  
  
# Follow the instructions, then use your name everywhere  
jules chat "What's the status of our project?"  
jules conversations  

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

RAG Memory Management

The CLI lets you add files directly to your agent's RAG (Retrieval Augmented Generation) memory. When your agent processes prompts, it searches these memories for relevant context.

Adding a Single File

ceo addRag ./docs/product-overview.md  

The file is automatically:

1. Read from disk
2. Chunked into manageable pieces (default 2000 characters per chunk)
3. Categorized based on file extension (e.g., .md → documentation, .js → code)
4. Embedded and stored in your agent's vector database

Adding an Entire Directory

# All supported files in docs/  
ceo addRagDir ./docs  
  
# Recursively include subdirectories  
ceo addRagDir ./project --recursive  
  
# Only markdown and text files  
ceo addRagDir ./knowledge-base --extensions md,txt --recursive  

Category Detection

Files are automatically categorized based on their extension:

| Category | Used For |
|----------|----------|
| code | Source files — the agent understands these as code |
| documentation | Docs, guides, text — the agent treats these as reference material |
| data | CSV, logs — the agent treats these as structured data |
| other | Anything else |

Override with --category:

ceo addRag ./notes.txt --category documentation  

Viewing Current Memories

ceo listMemories  

Workflow Example

# 1. Add your documentation  
ceo addRagDir ./docs --recursive  
  
# 2. Add relevant code  
ceo addRag ./src/core/api.js  
ceo addRag ./src/core/models.js  
  
# 3. Verify what was added  
ceo listMemories  
  
# 4. Now your agent has context for answering questions  
ceo chat "How does the API authentication work?"  

Getting Your API Key

1. Log in to CEO.AI Dashboard
2. Navigate to API Keys
3. Click Create API Key (NB: you must have a paid subscription to create api keys)
4. Select the agent you want to use
5. Copy the generated key (it will only be shown once)

Uninstall

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

Requirements

• Node.js 16 or later

• A CEO.AI account with an active API key and sufficient credits