@useago/cli

The official command-line interface for the AGO Public API. Manage your knowledge base, agents, conversations, and more — right from your terminal.

$ ago agents list
┌──────────────────────────────────────┬─────────────────────────┬──────────┬─────────────────────────┐
│ ID                                   │ Name                    │ Status   │ Display Name            │
├──────────────────────────────────────┼─────────────────────────┼──────────┼─────────────────────────┤
│ 8f2a1b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5 │ support-agent           │ active   │ Support Bot             │
│ a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6 │ sales-agent             │ active   │ Sales Assistant         │
└──────────────────────────────────────┴─────────────────────────┴──────────┴─────────────────────────┘

Total: 2

Install

npm install -g @useago/cli

Requires Node.js 18+.

Quick Start

# 1. Set your tenant and API key
ago config set-tenant acme          # → https://acme.useago.com
ago config set-key ago_v1_sk_xxx

# 2. Start using it
ago agents list
ago documents list --source FAQ
ago conversations list --email [email protected] --json | jq '.data[].id'

Configuration

The CLI resolves config in this order:

| Priority | Source | Example | |----------|--------|---------| | 1 | CLI flags | --tenant acme --api-key ago_v1_sk_xxx | | 2 | Environment variables | AGO_TENANT=acme AGO_API_KEY=ago_v1_sk_xxx | | 3 | Config file (~/.agorc) | ago config set-tenant acme |

ago config set-tenant mycompany     # Required — sets your subdomain
ago config set-key ago_v1_sk_xxx    # Required — your API key
ago config show                     # Verify current config

The config file is stored at ~/.agorc with 0600 permissions.

Usage

Every command supports --json for machine-readable output, and --help for usage details.

Knowledge Base

# Documents
ago documents list --source "Help Center" --search "billing"
ago documents get <id>
ago documents create --title "Getting Started" --content "Welcome to..."
ago documents update <id> --title "New Title"
ago documents delete <id>
ago docs bulk-delete id1 id2 id3

# Translations & Versions
ago documents translations <id>
ago documents add-translation <id> --language fr --title "Bonjour" --content "..."
ago documents versions <id>
ago documents restore-version <doc-id> <version-id>

# Sources
ago sources list --type zendesk
ago sources sync <id>
ago sources sync-history <id>
ago sources upload <source-id> ./article.pdf --title "Product Guide"

Agents & Tools

ago agents list --status active
ago agents create --name "support-v2" --display-name "Support Bot v2"
ago agents update <id> --custom-prompt "You are a helpful assistant..."
ago agents delete <id>

ago tools list
ago tools types                     # List available tool types
ago tools create --name "webhook" --type-id <type-id>

Conversations & Tickets

# Conversations (read-only)
ago conversations list --email [email protected] --start-date 2025-01-01
ago convos messages <thread-id>
ago convos feedback <thread-id>

# Tickets (read-only)
ago tickets list --status open --priority high
ago tickets stats --start-date 2025-01-01 --end-date 2025-12-31
ago tickets messages <ticket-id>

Prompt Templates & UI Templates

ago prompts list
ago prompts create --name "Support v2" --prompt "You are a support agent..."
ago prompts update <id> --prompt "Updated prompt..."

ago ui-templates list --active
ago ui-templates create --name "Card" --content "<div>...</div>"

Organizations, Users & Analytics

ago orgs list --search "Acme"
ago orgs email-domains <org-id>

ago users list --organization "Acme Corp" --search "john"

ago analytics dashboard --from 2025-01-01 --to 2025-12-31

Piping & Scripting

The --json flag outputs raw JSON, perfect for piping into jq or other tools:

# Get all agent IDs
ago agents list --json | jq -r '.data[].id'

# Count documents per source
ago documents list --json --page-size 100 | jq '.data | group_by(.source_name) | map({source: .[0].source_name, count: length})'

# Export conversation messages
ago convos messages <thread-id> --json > thread-export.json

# Bulk operations with xargs
echo "id1 id2 id3" | xargs ago documents bulk-delete

All Commands

| Command | Alias | Description | |---------|-------|-------------| | ago config | | Manage CLI configuration | | ago documents | docs | Manage knowledge documents | | ago sources | | Manage knowledge sources | | ago agents | | Manage agents | | ago conversations | convos | View conversations | | ago tickets | | View tickets | | ago tools | | Manage tools | | ago prompt-templates | prompts | Manage prompt templates | | ago ui-templates | | Manage UI resource templates | | ago organizations | orgs | View organizations | | ago users | | View users | | ago analytics | | View analytics |

API Scopes

Your API key needs the right scopes for each command:

| Commands | Required Scope | |----------|---------------| | documents, sources | knowledge:read / knowledge:write | | conversations | conversations:read | | tickets | tickets:read | | agents, tools, prompts, ui-templates | agents_config:read / agents_config:write | | organizations, users | accounts:read | | analytics | analytics:read |

Development

git clone <repo>
cd cli
npm install
npm run build           # Build with tsup
npm test                # Run tests (vitest)
npm run lint            # Type check (tsc --noEmit)
npm run dev             # Watch mode

License

MIT