Docana CLI

Manage your Docana workspace from the terminal: agents as versionable JSON files you can pull, edit, validate, diff, test, and push — plus documents, applications, environments, and conversations.

Install

npm install -g @docana/cli

Requires Node.js 20 or newer.

Log In

docana login

It opens your browser to log in — approve the request and you're done; the CLI keeps the session refreshed for you. You can also choose to paste an API key instead.

Login targets https://platform.docana.com. To point at a local or preview deployment, or to set a default application, use environment variables (or a docana.manifest.json for the application):

export DOCANA_API_URL=http://localhost:3000   # a different deployment
export DOCANA_APPLICATION_ID=your-app-id      # default application

For scripts and CI, authenticate with an API key via environment variables — DOCANA_API_KEY always wins over a stored browser login:

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

Check your setup with docana whoami.

The Core Loop

Agents are JSON specs. Work with them like code:

docana agents list                          # see what's there
docana agents pull <agent-id> -o agent.json # bring one down to a file
docana agents validate agent.json           # check it against the schema
docana agents diff agent.json               # compare with what's deployed
docana agents diff <prod-id> <dev-id>       # compare two different agents
docana agents versions <agent-id>           # list spec versions
docana agents diff <agent-id>@4 <agent-id>@9  # compare two versions
docana agents push agent.json -y            # ship it (updates the working version)
docana agents publish <agent-id>            # promote to the live version

For projects with several agents, evals, and routines, docana init creates a docana.manifest.json that maps local files to Docana entities, and plain docana pull / docana validate / docana push -y operate on the whole project. Start from the project template, and see Agent Projects for the manifest reference.

Run and Test

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

# Run a spec against an eval and report results
docana agents eval agent.json -e eval-spec.json -a <application-id>

# Print JSON Schemas for editor autocomplete and validation
docana agents schema > agent-schema.json
docana agents eval-schema > eval-schema.json

Secrets and Environments

Agent secrets (provider API keys) live in Docana application environments, stored encrypted server-side and read by specs as {{env.KEY}} — never in your repo:

docana app <application-id> envs ls
docana app <application-id> envs create -n production -v API_KEY=xxx
docana app <application-id> envs update <env-id> --variables-json '{"API_KEY":"yyy"}'

Note: envs update replaces the whole variable set — pass every variable, not just the changed one.

Call the API Directly

For anything without a dedicated command, docana api is a raw client that reuses your login — no auth headers or tokens to manage:

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

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

schema search keeps the output small enough for a coding agent to read whole, which is exactly what it's for.

Everything Else

| Area | Commands | | ------------- | ------------------------------------------------------------------------------------- | | Agents | agents list / pull / push / publish / validate / run / eval / diff / open / alias | | Agent runs | agents runs list / search / get / stop / open, agents eval-run list / get / watch | | Agent evals | agents eval-case list / get / update / run | | Documents | documents list / push / pull / search, document open | | Knowledge | libraries list / create, collections list / create | | Applications | applications list / create, app <id> envs / allowed-websites / chat / open | | Conversations | chat, thread list / messages / open | | Raw API | api <method> <path>, api schema [search <query>] |

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

Learn More

• CLI guide
• Agent Projects & the manifest
• Project template repository
• Testing agents
• REST API and Docana MCP