Skip to main content

CLI

Building agents by clicking is great until you want version control, code review, and CI. The Docana CLI (docana) turns agents into JSON files you can pull, edit, diff, test, and push, plus it handles documents, applications, and conversations from the terminal.

Install and Log In​

npm install -g @docana/cli

docana login

docana login asks how to sign in: log in with your browser (recommended — approves against your existing Docana session, no key to create or paste) or paste an API key. Browser login uses short-lived tokens that refresh automatically for 30 days.

Login targets https://platform.docana.com. To use a local or preview deployment, or set a default application, use the environment variables below (or a docana.manifest.json for the application) — they're the advanced path, not a prompt.

For scripts and CI, skip the prompt and set environment variables:

export DOCANA_API_URL=https://platform.docana.com
export DOCANA_API_KEY=your-api-key
export DOCANA_APPLICATION_ID=your-app-id

Check your setup with docana whoami.

The Core Loop: Pull, Edit, Push​

Agents are JSON specs. The workflow looks like working with code, because it is:

# See what's there
docana agents list

# Bring an agent down to a file
docana agents pull <agent-id> -o support-agent.json

# Edit the file in your editor, then check it
docana agents validate support-agent.json

# See what changed compared to what's deployed
docana agents diff support-agent.json

# Ship it
docana agents push support-agent.json -y

Agent IDs are long, so give them names: docana agents alias set support <agent-id>, then use support anywhere an ID goes.

For multi-agent projects, docana init creates a docana.manifest.json that maps local files to agents, and plain docana pull, docana validate, and docana push -y operate on the whole project. See Agent Projects for the manifest reference and a template repository to start from.

Run and Test Agents​

# Run an agent spec with a prompt, streaming the response
docana agents run support-agent.json "What's our refund policy?" --app-id <application-id>

# Run it with a test case and evaluations, and report results
docana agents eval support-agent.json -e eval-spec.json -a <application-id>

docana agents eval in CI means a broken agent fails the build instead of failing a customer. See Testing Agents for what goes in a test case.

To write specs with autocomplete and validation in your editor:

docana agents schema > agent-schema.json
docana agents eval-schema > eval-schema.json

AI Coding Assistants​

If an AI assistant (Claude Code, Cursor, ...) edits your specs, the CLI has a guide written for it:

docana help ai

It prints the agent design rules, transition semantics, template variables, and the full command list in one page — everything an assistant needs to author specs without guessing. The template repository ships an AGENTS.md that points assistants at it automatically.

Finding Executions​

When something looks off for a specific customer, search your agent's runs by who started them — name, email, or phone. You only need the agent; the application is taken from it:

docana agents runs search "Acme Corp" --agent-id <agent-id>

Give the agent a name once and drop the long id — --agent-id takes an alias:

docana agents alias set prod <agent-id>
docana agents runs search "Acme Corp" --agent-id prod

Or use the positional form — docana agent <id-or-alias> <command> operates on one agent, the same way docana app <id> scopes to one application:

docana agent prod runs search "Acme Corp"
docana agent prod runs list --errors
docana agent prod run "Ping"      # also: open, pull

The results show the customer, status, and when each run happened. Narrow further with --status RUNNING,FINISHED, --errors (only runs that failed), --type LIVE, or a date range with --from and --to. Add --content to also match the message text, and docana agents runs get --execution-id <id> for the full node-by-node trace of one run.

Beyond Agents​

The CLI covers the rest of the platform too:

AreaCommands
Agentsagents list / pull / push / publish / validate / run / eval / diff / open / alias
Agent runsagents runs list / search / get / stop, agents eval-run list / get / watch
Documentsdocuments list / push / pull / search, document open
Knowledgelibraries list / create, collections list / create
Applicationsapplications list / create
Conversationschat, thread list, thread messages

Run docana help or add --help to any command for flags and details.

Pointing at Different Environments​

The CLI talks to whatever DOCANA_API_URL points at. The same commands work against production, a local instance, or a staging deployment. Switch environments by switching the variable.

Next Steps​