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 for your API URL (https://platform.docana.com), your API key (see Generating API Keys), and an optional default application ID.
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.
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
Beyond Agents
The CLI covers the rest of the platform too:
| Area | Commands |
|---|---|
| Agents | agents list / pull / push / publish / validate / run / eval / diff / open / alias |
| Agent runs | agents runs list / get / stop, agents eval-run list / get / watch |
| Documents | documents list / push / pull / search, document open |
| Knowledge | libraries list / create, collections list / create |
| Applications | applications list / create |
| Conversations | chat, 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
- Generating API Keys - The key the CLI authenticates with
- Testing Agents - The eval concepts behind
docana agents eval - API Overview - Call the API directly instead