@duvoai/cli

Command-line interface for the Duvo public API.

Install

npm install -g @duvoai/cli

Requires Node.js ≥ 22.22.0.

Or install the standalone binary (no Node.js required):

curl -fsSL https://duvo.ai/install-cli.sh | sh

Update

duvo update

duvo update detects how the CLI was installed and updates in place: npm installs run npm install -g @duvoai/cli@latest; the standalone binary downloads the latest release, verifies its checksum, and replaces itself. Use duvo update --check to see whether a newer version exists without installing it.

Deprecation notices

When the API marks an endpoint as deprecated, this CLI prints a short warning to stderr (with the sunset date and a link if the server provides them). Deprecation warnings always show — they don't affect stdout and can't be silenced.

Quick start

# 1. Log in (prompts for your API key and saves it to a profile)
duvo login --name default

# 2. Verify you're logged in
duvo whoami

# 3. Create your first agent (interactive)
duvo agents create

# ...or create one non-interactively with flags
duvo agents create --name "My agent" --input "What this agent should do"

# ...optionally pick the LLM the agent runs on
duvo agents create --name "My agent" --model claude-opus-4-7

# 4. Kick off a run and watch it complete
duvo runs start --agent <agent-id> --follow

# Switch an existing agent to a different model later
duvo agents set-model <agent-id> --model claude-opus-4-7

Grab an API key from your team settings: https://app.duvo.ai/settings/api-keys.

Authentication

You can keep multiple profiles and switch between them:

duvo login --name acme         # prompts for the API key
duvo login --name team-2       # prompts for the API key

duvo profiles list             # show saved profiles
duvo profiles use acme         # set the default profile
duvo --profile team-2 whoami   # one-off override for a single command

Workflows

Start a run and stream messages

# Start a run and tail messages until it completes
duvo runs start --agent <agent-id> --message "Process this week's reports" --follow

# Tail messages on a run that's already in progress
duvo runs messages <run-id> --follow

--follow polls for new messages every 2 s and exits when the run reaches a terminal state (completed, failed, stopped, or error). The final line always shows the run's status, e.g. Run completed.

To consume the stream programmatically, combine --follow --json: each new message is printed as a JSON object on its own line (NDJSON).

duvo runs messages <run-id> --follow --json | while IFS= read -r line; do
  echo "$line" | jq -r '.text_content // empty'
done

Scripting with --json

Every command accepts --json to emit the raw API response instead of a table or key/value view — useful for piping to jq.

# Start a run and capture the ID
RUN_ID=$(duvo runs start --agent "$AGENT_ID" --message "Go" --json | jq -r '.run.id')

# Follow messages on that run
duvo runs messages "$RUN_ID" --follow

Set up connections for an agent revision

Integrations represent slots in a revision that need live credentials (a connection). Use revision-integrations to see the slots and revision-integrations connections to pin your connections to them.

# 1. See the integration slots on a revision
duvo revision-integrations list --agent <agent-id> --revision <revision-id>
# INTEGRATION ID  TYPE   NAME   SLOT ID   CREATED
# 22222222-...    gmail  Gmail  slot-1    2026-04-15…

# 2. List your available connections
duvo connections list --type gmail

# 3. Pin a connection to the slot (use SLOT ID or INTEGRATION ID from step 1)
duvo revision-integrations connections pin <connection-id> \
  --agent <agent-id> --revision <revision-id> --integration slot-1

# 4. Verify
duvo revision-integrations connections list \
  --agent <agent-id> --revision <revision-id> --integration slot-1

Note: The --integration flag accepts either the SLOT ID or the INTEGRATION ID column from revision-integrations list.

Work with queues

# Create a queue
duvo queues create --name "support-tickets"

# On a team that has moved to the Automations workspace, a queue has to be
# created inside an automation — `duvo automations list` gives you the id
duvo queues create --name "support-tickets" --automation-id <automation-id>

# `duvo agents create` takes the same flag; without it a new agent gets an
# automation of its own rather than joining an existing one
duvo agents create --name "Ticket triage" --automation-id <automation-id>

# Create cases in bulk from a JSON file (up to 100)
duvo cases create --queue <queue-id> --from-file cases.json

# List pending cases
duvo cases list --queue <queue-id> --status pending

# Count pending cases without fetching Case rows
duvo cases list --queue <queue-id> --status pending --count-only

# Get case status counts for several queues in one call
duvo queues stats --queue-ids <id1>,<id2>,<id3>

# Bulk re-process pending cases on an agent
duvo cases bulk-reprocess --queue <queue-id> --agent <agent-id> \
  --ids <id1>,<id2>,<id3>

Human-in-the-loop responses

When a run pauses and asks a question, respond directly from the CLI:

duvo runs get <run-id>              # shows pending_human_request details
duvo runs respond <run-id>          # defaults to the current pending request

Commands

Clarity commands auto-detect process version where possible. The legacy v1 format uses a single analysis payload, while v2 is snapshot-based with current-process and transformation-proposal versions. Use v2-specific commands such as versions, current, proposal, compare, gaps, evidence, and readiness only for v2 processes.

Default output is summary-first and compact. JSON output also includes a compact summary block, while capture transcripts and media URLs are omitted unless --include-transcripts is passed.

duvo agents schedules list --all-users returns at most one response's worth of rows. On an agent with more schedules than that, the CLI warns that some are missing, and the rows it does return are the oldest by creation date.