Command Line Interface

Manage your AGO workspace from the terminal with the ago CLI

The @useago/cli package wraps the Public API v1 so you can manage knowledge documents, agents, conversations, tickets, and analytics from your terminal. Read commands accept --json for piping into jq or other shell tools.

Install

npm install -g @useago/cli

Requires Node.js 18 or later.

Configure

Set your tenant subdomain and API key once, then run any command:

ago config set-tenant acme            # → https://acme.useago.com
ago config set-key ago_v1_sk_xxx
ago config show                       # verify

The config is saved to ~/.agorc with 0600 permissions.

If you run AGO at a non-standard URL (custom domain, staging environment), set an explicit base URL instead of a tenant:

ago config set-url https://ago.example.com
ago config unset-tenant                # remove a previously saved tenant
ago config unset-url                   # remove a previously saved base URL

You can also pass credentials per-command, or via environment variables. Order of precedence:

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 AGO_BASE_URL=…
3	Config file (~/.agorc)	ago config set-tenant acme

Create your API key from Admin → Settings → API Keys. See API Key Authentication for scope details.

Commands

Command	Alias	What it does
ago config		Set or read CLI configuration
ago documents	docs	Manage knowledge documents
ago sources		Manage knowledge sources and run syncs
ago agents		Create, update, list, delete agents
ago tools		Manage agent tools
ago prompt-templates	prompts	Manage prompt templates
ago ui-templates		Manage UI resource templates
ago conversations	convos	Read conversations and feedback
ago tickets		Read tickets and ticket statistics
ago organizations	orgs	Read organizations and email domains
ago users		Read users
ago analytics		Read dashboard analytics

Append --help to any command for a full list of subcommands and flags:

ago documents --help
ago documents create --help

Knowledge

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

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 documents bulk-delete id1 id2 id3

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>

Agents and 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
ago tools create --name "webhook" --type-id <type-id>

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

Conversations and tickets

Conversations and tickets are read-only from the CLI:

ago conversations list --email [e-mail] --start-date 2026-01-01
ago convos messages <thread-id>
ago convos feedback <thread-id>

ago tickets list --status open --priority high
ago tickets stats --start-date 2026-01-01 --end-date 2026-12-31
ago tickets messages <ticket-id>

Organizations, users, and analytics

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

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

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

JSON output and scripting

Read commands accept --json for raw JSON instead of formatted tables, suitable for piping:

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

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

# Export a thread to a file
ago convos messages <thread-id> --json > thread-export.json

# Bulk delete from a list
echo "id1 id2 id3" | xargs ago documents bulk-delete

API key scopes

Each command needs the matching scope on your API key:

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

If a command returns a permission error, check the scopes on the key under Admin → Settings → API Keys.

Related

• Public API v1 — REST reference for all endpoints the CLI calls
• API Key Authentication — Create keys and assign scopes
• MCP Server — Same operations via Model Context Protocol