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 signs you in with your browser (recommended) or an API key. Browser login refreshes automatically for 30 days.

Browser login stores an OAuth access token and a refresh token in ~/.docana/config.json. The access token lives for one hour. The CLI refreshes it before each request, so you never notice. If your own script reads accessToken from that file instead of going through the CLI, it has to refresh too, or it starts getting 401 after an hour. Scripts are usually better off with an API key, which does not expire.

For scripts and CI, set environment variables instead:

export DOCANA_API_URL=https://platform.docana.com
export DOCANA_API_KEY=your_api_key_here
export DOCANA_APPLICATION_ID=1234567890123

The CLI talks to whatever DOCANA_API_URL points at: production, a local instance, or a preview. docana whoami shows your current setup.

Create and prepare employees​

docana employees exposes the same employee setup and evidence as the UI. Create an employee from a JSON definition, prepare it from a goal, and continue with the returned conversation ID:

docana employees templates --locale en-US
docana employees create employee.json
docana employees prepare <application-id> "Prepare a draft and tests for this job."
docana employees knowledge <application-id>
docana employees status <application-id>
docana employees performance <application-id>

See Employees from code for identity and persona fields, the complete REST/MCP/CLI mapping, source uploads, tests, and secure website logins.

Edit agents as files​

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 name them: docana agents alias set support <agent-id>, then use support anywhere an ID goes.

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

Compare agents and versions​

Either side of docana agents diff can be a file, an agent ID, or an alias, and @N picks a version from the agent's history:

# A local edit against its deployed version
docana agents diff support-agent.json

# Two deployed agents, e.g. prod vs dev
docana agents diff prod-support dev-support

# Two versions of one agent
docana agents versions support
docana agents diff support@4 support@9

The diff starts with a summary in agent terms (reasonings, routing rules, workflow nodes), then shows the full side-by-side spec diff. Specs are normalized first, so internal IDs don't show up as noise. One caveat: historical versions show evaluation criteria as they are today, not as they were then.

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.

For autocomplete and validation in your editor, save the schemas: docana agents schema and docana agents eval-schema.

Search executions​

When something looks off for a specific customer, search your agent's runs by who started them: name, email, or phone. The application comes from the agent, and --agent-id takes an alias:

docana agents runs search "Acme Corp" --agent-id prod

Or scope to one agent with the positional form:

docana agent prod runs search "Acme Corp"
docana agent prod runs list --errors

Narrow with --status, --errors, --type, or --after and --before. Add --content to also match message text, and docana agents runs get --execution-id <id> for the full node-by-node trace of one run.

Open in the browser​

Every open command jumps from the terminal to the matching platform.docana.com page:

docana agent <id> open                    # the agent builder
docana agent <id> runs open <exec-id>     # an execution's trace
docana thread open <thread-id>            # a conversation
docana app <id> open                      # an application's assistant
docana document open <doc-id>             # a document

Call the API directly​

docana api calls any endpoint the REST API exposes, reusing your login. -d takes inline JSON, @file, or @- for stdin:

docana api GET /api/v1/applications/
docana api POST /api/v1/agents/import/?applicationId=42 -d @agent.json

Query parameters go after the path as key=value arguments, or inside the path as a query string. Both page through a collection:

docana api GET /api/v1/collections/42/documents/ limit=100 page=2
docana api GET '/api/v1/collections/42/documents/?limit=100&page=2'

To learn the surface instead of guessing endpoints, dump the deployment's OpenAPI document, or search it:

docana api schema                     # the full OpenAPI document
docana api schema search executions   # just the matching operations

AI coding assistants​

If an AI assistant (Claude Code, Cursor, ...) edits your specs, docana help ai prints the agent design rules and full command list in one page, and docana api schema search <topic> teaches it the API. The template repository ships an AGENTS.md that points assistants at both automatically.

Command reference​

Add --help to any command for its full flags. Most list and get commands take --json.

Agents​

  • docana agents list: list agents in an application
  • docana agents pull <agent> -o <file>: save a spec to a file
  • docana agents push <file> -y [--publish]: upload a spec, optionally make it live
  • docana agents publish <agent>: make the latest pushed spec live
  • docana agents validate <file>: check a spec against the schema
  • docana agents diff <left> [right]: compare files, agents, and @N versions
  • docana agents versions <agent>: list an agent's spec versions
  • docana agents run <agent-or-file> "<prompt>": run and stream the response
  • docana agents open <agent>: open the agent builder
  • docana agents alias set / list / remove: name agents
  • docana agents schema / eval-schema: print the JSON schemas
  • docana agent <agent> runs / open / run / pull: shortcut scoped to one agent

Runs and evals​

  • docana agents runs list / search / get / stop / open: list, search, trace, cancel, or open executions
  • docana agents eval <file> -e <eval-spec>: run test cases and report results
  • docana agents eval-case list / get / update / run: manage individual test cases
  • docana agents eval-run list / get / watch / stop / delete: inspect eval runs

Insights, branches and experiments​

  • docana agents insights get / set / clear: read, replace, or clear an agent's Conversation Insights config
  • docana agents insights nodes: list the workflow nodes a node-sourced data point can measure
  • docana agents insights backfill: measure node-sourced points over past conversations
  • docana agents branches list / create / show / preview / promote / discard: candidate versions of an agent; use docana api for branch rename or direct artifact editing
  • docana agents experiments setup / start / list / show / pause / resume / stop / publish: run and manage an A/B experiment, including exact-pin publication
  • docana api GET /api/v1/agents/<id>/analytics/insights/ applicationId=<app>: read Conversation Insight aggregates; pollAgentInsights is the separate document Insights API

Agent projects​

  • docana init: create a project manifest
  • docana pull / validate / push [selector]: operate on every agent in the manifest

Documents and knowledge​

  • docana documents list / search: list or search documents
  • docana documents push <collection-id> <paths...> [-r] [-f <folder-id>]: upload files to a collection. With --recursive, directories are walked and their structure mirrored as folders
  • docana documents move <document-id> -c <collection-id> [-f <folder-id>]: move a document into a folder, or with -t <collection-id> into another collection without re-ingesting it
  • docana documents pull <document-id> -o <file>: download a document
  • docana document chat <document-id> "<prompt>": ask questions to one document
  • docana document open <document-id>: open it in the browser
  • docana libraries list / create: knowledge libraries
  • docana collections list / create: collections inside a library

Applications​

  • docana applications list / create <name>: list applications or create one
  • docana apps collections enable / disable <app-id> <collection-id>: enable a collection on an application's knowledge
  • docana apps collections file-sharing <app-id> <collection-id> <on|off>: let the assistant send that collection's files to end users
  • docana apps persona show <app-id>: the application's current persona and tone of voice
  • docana apps persona set <app-id> --preset <id>: set the voice, with optional trait sliders (--formality through --emoji, 0 to 4) and --notes
  • docana apps persona clear <app-id>: return to the default (neutral) voice
  • docana app <id> open / chat "<prompt>": open or chat with the assistant
  • docana app <id> envs list / create / show / update / rm: environment variables
  • docana app <id> allowed-websites list / create / set-credentials / rm: sites agents may browse
  • docana browser-context reset --app-id <id>: reset the app's persistent browser session

MCP servers​

  • docana mcp-servers list / get: the MCP servers visible to you
  • docana mcp-servers create / update / rm: register, edit, or delete a server
  • docana mcp-servers test <id>: check the connection by listing the server's tools
  • docana mcp-servers authorize / connections: run and inspect per-user OAuth connections
  • docana app <id> mcp ls / enable / disable <server-id>: choose which servers an application's agents can use

Conversations​

  • docana thread list --scope <app|document|agent>: list threads
  • docana thread messages: list the messages in a thread
  • docana thread open <thread-id>: open a conversation in the browser

Setup and raw API​

  • docana usage [--json]: this month's budget, what is used, and what remains
  • docana login / docana whoami: sign in and check your setup
  • docana help ai: print the spec guide for AI assistants
  • docana api <METHOD> <path> [-d <json>]: call any REST endpoint
  • docana api schema [search <query>]: dump or search the OpenAPI document

Next steps​

Shared company categories​

docana categories list returns the categories shared by Employees and Applications. Add --locale pt-BR for Portuguese defaults. Administrators can create a category with docana categories create category.json and rename it or change its icon with docana categories update <key> category.json. The JSON accepts name and icon. Use the returned key in an employee's categoryKey or docana apps create --category <key>.

docana employees status <id> includes knowledge counts, known pages, processing state, and file types. docana employees files <id> --search policy --limit 50 returns a bounded source list. Continue with --cursor <next_cursor>. See Employees from code for the matching REST and MCP operations.