Scripting and CI/CD Patterns

The Duvo CLI is designed to run in scripts and automation pipelines, not just interactively. This page covers how to authenticate in non-interactive environments, common automation patterns, and three complete worked examples.

Authentication in CI/CD and scripts

Use an API key, not OAuth

OAuth sessions require a browser login and are bound to a user’s session. For CI/CD pipelines and server-side scripts, use an API key instead. Generate a key at Team Settings → API Keys and store it as a secret environment variable in your CI system (GitHub Actions secrets, GitLab CI variables, AWS Secrets Manager, etc.).

Pass the key as an environment variable

The CLI reads DUVO_API_KEY automatically, so you never need to touch a config file or run duvo login in a pipeline:

DUVO_API_KEY="dv_..." duvo agents list --json

Or export it once at the top of your script:

export DUVO_API_KEY="${DUVO_API_KEY}"  # sourced from environment
duvo agents list --json
duvo runs start --agent "$AGENT_ID" --json

Rotating API keys

API keys do not expire by default. Rotate them by:

Creating a new key at Team Settings → API Keys.
Updating the key in your CI secret store.
Deleting the old key from the dashboard.

There is a brief window between steps where both keys are valid — this ensures zero-downtime rotation. If a key is compromised, delete it immediately and treat any Runs that ran under it as potentially untrusted.

GitHub Actions example

jobs:
  duvo-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @duvoai/cli
      - run: duvo agents list --json
        env:
          DUVO_API_KEY: ${{ secrets.DUVO_API_KEY }}

Common scripting patterns

Start a Run and wait for it to finish

duvo runs start returns immediately. Poll duvo runs get until the Run reaches a terminal status:

RUN_ID=$(duvo runs start \
  --agent "$AGENT_ID" \
  --message "Process the daily batch." \
  --json | jq -r '.run.id')

while true; do
  STATUS=$(duvo runs get "$RUN_ID" --json | jq -r '.run.status')
  case "$STATUS" in
    completed|failed|stopped) break ;;
  esac
  sleep 10
done

if [ "$STATUS" != "completed" ]; then
  echo "Run failed with status: $STATUS" >&2
  exit 1
fi
echo "Run $RUN_ID completed."

Upload files before starting a Run

When your Agent needs to process files, create a sandbox, upload the files, and pass the sandbox ID to the run:

SANDBOX_ID=$(duvo sandboxes create --json | jq -r '.sandbox.id')

duvo sandboxes upload "$SANDBOX_ID" ./input-data.csv

RUN_ID=$(duvo runs start \
  --agent "$AGENT_ID" \
  --sandbox-id "$SANDBOX_ID" \
  --json | jq -r '.run.id')

For files larger than 10 MB, get a presigned URL and upload directly:

UPLOAD=$(duvo sandboxes prepare-upload-url "$SANDBOX_ID" \
  --path /workspace/data.csv --json)
URL=$(echo "$UPLOAD" | jq -r '.upload_url')
curl -X PUT --data-binary "@./data.csv" "$URL"

Bulk-reprocess Cases on an Agent

When you need to route a set of Cases to a specific Agent — for example, assigning a backlog of items after a new Agent is deployed. Any active Runs for the specified Cases are interrupted:

duvo cases bulk-reprocess \
  --queue "$QUEUE_ID" \
  --agent "$AGENT_ID" \
  --ids "case-1,case-2,case-3,case-4,case-5" \
  --yes

--ids accepts a comma-separated list of up to 100 Case IDs. The --yes flag skips the confirmation prompt, which is required in non-interactive scripts.

Collect Run output from a completed run

After a Run finishes, pull the assistant’s messages to feed the output into downstream systems:

duvo runs messages "$RUN_ID" --json \
  | jq -r '[.messages[] | select(.role=="assistant") | .content] | join("\n")'

Roll out an Agent config change to multiple Agents

When a shared config file is updated (for example, a common AOP or tool set), push it as a new Revision across every affected Agent:

REVISION_NAME="config-update-$(date +%Y%m%d)"

for AGENT_ID in agent-id-1 agent-id-2 agent-id-3; do
  duvo revisions create \
    --agent "$AGENT_ID" \
    --name "$REVISION_NAME" \
    --config-file ./shared-config.json
  echo "Updated $AGENT_ID"
done

Worked examples

Example 1: One-shot Run trigger

Trigger a Run from any shell or pipeline and print the final output. Exit non-zero if the Run fails.

#!/usr/bin/env bash
set -euo pipefail

AGENT_ID="$1"          # pass as argument: ./trigger-job.sh <agent-id>
MESSAGE="${2:-}"       # optional message

RUN_ID=$(duvo runs start \
  --agent "$AGENT_ID" \
  ${MESSAGE:+--message "$MESSAGE"} \
  --json | jq -r '.run.id')

echo "Started Run: $RUN_ID"

while true; do
  STATUS=$(duvo runs get "$RUN_ID" --json | jq -r '.run.status')
  case "$STATUS" in
    completed|failed|stopped) break ;;
  esac
  sleep 10
done

echo "Run finished: $STATUS"

# Print the last assistant message
duvo runs messages "$RUN_ID" --json \
  | jq -r '.messages[] | select(.role=="assistant") | .content' \
  | tail -1

[ "$STATUS" = "completed" ] || exit 1

Example 2: Nightly Agent config sync from Git

Store Agent configs as JSON files in a Git repository and push any changed configs to Duvo on every merge to main. This lets you version-control your Agent Setups alongside your application code. Repository layout:

assignments/
  invoice-processor.json
  order-tracker.json
  supplier-follow-up.json
agent-ids.env          # INVOICE_PROCESSOR_ID=abc123 ...

Sync script (.github/workflows/sync-assignments.yml):

name: Sync Agents

on:
  push:
    branches: [main]
    paths:
      - "assignments/**"

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2 # need HEAD and HEAD^ to diff

      - run: npm install -g @duvoai/cli

      - name: Push changed configs
        env:
          DUVO_API_KEY: ${{ secrets.DUVO_API_KEY }}
        run: |
          source agent-ids.env
          CHANGED=$(git diff --name-only HEAD^ HEAD -- assignments/)

          for FILE in $CHANGED; do
            NAME=$(basename "$FILE" .json)
            VAR_NAME=$(echo "$NAME" | tr '[:lower:]-' '[:upper:]_')_ID
            AGENT_ID="${!VAR_NAME:-}"

            if [ -z "$AGENT_ID" ]; then
              echo "No Agent ID for $NAME — skipping."
              continue
            fi

            duvo revisions create \
              --agent "$AGENT_ID" \
              --name "git-$(git rev-parse --short HEAD)" \
              --config-file "$FILE"

            echo "Synced $NAME ($AGENT_ID)"
          done

Only files changed in the push are synced, so the workflow is fast even with many Agent files in the repo.

Example 3: Weekly Run-status report

Run weekly in CI to summarize how many Runs completed, failed, or are still running across your key Assignments. Post the summary wherever your team receives reports.

#!/usr/bin/env bash
set -euo pipefail

# Space-separated list of Agent IDs to include in the report
AGENTS="agent-id-1 agent-id-2 agent-id-3"

completed=0
failed=0
stopped=0

for AGENT_ID in $AGENTS; do
  RUNS=$(duvo runs list --agent "$AGENT_ID" --limit 100 --json 2>/dev/null \
    || echo '{"runs":[]}')

  completed=$((completed + $(echo "$RUNS" | jq '[.runs[] | select(.status=="completed")] | length')))
  failed=$((failed     + $(echo "$RUNS" | jq '[.runs[] | select(.status=="failed")] | length')))
  stopped=$((stopped   + $(echo "$RUNS" | jq '[.runs[] | select(.status=="stopped")] | length')))
done

total=$((completed + failed + stopped))

echo "Weekly Run Summary"
echo "=================="
echo "Completed : $completed / $total"
echo "Failed    : $failed / $total"
echo "Stopped   : $stopped / $total"

Pipe the output to slack-cli, mail, or any notification tool your team uses.

Tips

Always add --yes to bulk operations (bulk-reprocess, bulk-update-status, cases delete) in scripts so they don’t block waiting for confirmation.
Combine --json with jq for all scripting — human-readable output can change between CLI versions, but JSON is stable.
Set DUVO_PROFILE to target a non-default profile (e.g., staging) without changing your shell’s default: DUVO_PROFILE=staging duvo runs start --agent "$AGENT_ID" --json.
Run duvo <command> --help to see the full flag set for any command.

Starting Runs — full command reference for duvo runs
Managing Agents — creating Agents and Revisions
Cases and Queues — bulk Case operations
Advanced Commands — duvo api, sandboxes, and raw API access
Public API Reference — REST alternative if you need more than the CLI offers

​Authentication in CI/CD and scripts

​Use an API key, not OAuth

​Pass the key as an environment variable

​Rotating API keys

​GitHub Actions example

​Common scripting patterns

​Start a Run and wait for it to finish

​Upload files before starting a Run

​Bulk-reprocess Cases on an Agent

​Collect Run output from a completed run

​Roll out an Agent config change to multiple Agents

​Worked examples

​Example 1: One-shot Run trigger

​Example 2: Nightly Agent config sync from Git

​Example 3: Weekly Run-status report

​Tips

​Related