> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Duvo CLI

> Install and use the Duvo CLI to manage Agents, start Runs, move Files, and drive the Duvo API from your terminal or CI/CD pipelines.

## Agent Skills for the CLI

The best way to use the Duvo CLI is alongside the public [Duvo Agent Skills repository](https://github.com/duvoai/skills). It's a free, open repository of skills you can download and combine with the CLI to get far more out of it — they teach Claude Code, Codex, Cursor, and other coding agents to operate Duvo directly: manage Agents, debug failed Runs, and write the AOPs that drive them, all without leaving your editor or terminal.

It packages three ready-made skills:

* **`duvo-cli`** — drive the full CLI (Agents, Runs, Cases, Queues, Files, Connections) through your agent
* **`sop-writer`** — draft, rewrite, or critique Agent AOPs
* **`job-debugger`** — analyze failed Runs, find the root cause, and propose fixes

Download the skills, then install the CLI they drive:

<Steps>
  <Step title="Download the Duvo agent skills" icon="download">
    ```bash theme={"dark"}
    npx skills add duvoai/skills       # download the Duvo agent skills
    ```
  </Step>

  <Step title="Install the CLI" icon="terminal">
    <CodeGroup>
      ```bash curl (macOS / Linux) theme={"dark"}
      curl -fsSL https://duvo.ai/install-cli.sh | bash
      ```

      ```bash npm theme={"dark"}
      npm install -g @duvoai/cli         # requires Node.js 24+
      ```
    </CodeGroup>
  </Step>

  <Step title="Sign in" icon="log-in">
    ```bash theme={"dark"}
    duvo login                         # sign in
    ```
  </Step>

  <Step title="Confirm you're connected" icon="check">
    ```bash theme={"dark"}
    duvo whoami                        # confirm you're connected
    ```
  </Step>
</Steps>

Once installed, ask your agent things like "investigate why my last Run failed" or "rewrite this AOP to be clearer" and it will use the CLI for you.

## Use with Claude Code

If you'd rather prime an agent by hand instead of installing the skills above, paste the prompt below into [Claude Code](https://www.anthropic.com/claude-code) (or any other coding agent) to teach it how to drive the Duvo CLI on your behalf. It primes the agent to install `duvo`, sign in, and use the right commands for the task you ask for next.

```text Claude Code prompt [expandable] theme={"dark"}
You are pairing with me on a project that uses the Duvo CLI (`duvo`) to manage AI Agents, Runs, Connections, Files, and Cases. Follow these rules whenever I ask you to do anything Duvo-related.

# Setup
1. Check if the CLI is installed: `duvo --version`. If it is missing, install it with `curl -fsSL https://duvo.ai/install-cli.sh | bash` (macOS/Linux), or `npm install -g @duvoai/cli` (requires Node.js 24+).
2. Check authentication with `duvo whoami`. If I am not signed in, run `duvo login` (interactive OAuth) or `duvo login --api-key <key>` for non-interactive shells. Ask me which to use if it is unclear.
3. If I mention multiple teams or environments, use named profiles: `duvo login --name <profile>` and `--profile <name>` on individual commands. Never change my default profile without asking.

# How to work
- Always pass `--json` and pipe through `jq` when you need to parse output. Never scrape the human-friendly tables.
- Before running a command, run `duvo <command> --help` if you are not 100% sure of the flags.
- Prefer the dedicated command groups over `duvo api`. Fall back to `duvo api <METHOD> <path>` only when no dedicated command exists.
- For destructive actions (delete, stop, replace, bulk delegate), show me the exact command and wait for confirmation before executing.
- Surface IDs (Agent ID, Run ID, Connection ID, Case ID, Queue ID) in your responses so I can reuse them.

# Command map
- Agents / workflows: `duvo agents`, `duvo agent-folders`, `duvo revisions`
- Starting Runs automatically: `duvo agents schedules`, `duvo agents triggers`, `duvo agents case-triggers`
- Starting Runs (incl. human-in-the-loop): `duvo runs`
- Connections and integrations: `duvo connections`, `duvo integrations`, `duvo oauth`
- Secrets and logins: `duvo secrets`, `duvo credentials`, `duvo revision-secrets`, `duvo revision-logins`
- Files, Skills, and Plugins: `duvo files`, `duvo skills`, `duvo plugins`
- Cases and Queues: `duvo cases`, `duvo queues`, `duvo queue-labels`
- Clarity (read-only): `duvo clarity`
- Profiles and teams: `duvo profiles`, `duvo team`, `duvo teams`
- Escape hatches: `duvo api`, `duvo sandboxes`

# Output
When you finish a task, give me: (1) the commands you ran, (2) the key IDs or results, (3) a suggested next step.

Docs: https://docs.duvo.ai/cli
```

The rest of this page is the human-readable reference for the same commands.

## Overview

The Duvo CLI (`duvo`) brings Duvo to your terminal. Use it from scripts, CI/CD pipelines, and developer workflows to manage Agents, Connections, Files, Runs, and more — without leaving the command line.

The CLI is a wrapper around the [Public API](../api-reference), so anything you can do via the API you can do with `duvo`. JSON output is built in for scripting, and named profiles let you switch between teams or environments instantly.

## What you can do

* **Start Runs and respond to humans-in-the-loop** — Start Runs, stream messages live, approve or deny requests, send mid-run instructions.
* **Manage Agents** — List, create, update, delete, and organize Agents into folders.
* **Start Runs automatically** — Set up schedules, event triggers, and Case triggers.
* **Manage Connections, secrets, and logins** — Authorize OAuth Connections, store env-var secrets and logins, and attach them to a Revision.
* **Move Files and build Skills** — Upload documents to the team file library, and create, install, and edit Skills.
* **Work with Cases and Queues** — Inspect Case history, delegate Cases in bulk, manage labels.
* **Hit the raw API** — Call any Duvo endpoint via `duvo api` when you need something a dedicated command doesn't cover yet.

## Installation

<CodeGroup>
  ```bash curl (macOS / Linux) theme={"dark"}
  curl -fsSL https://duvo.ai/install-cli.sh | bash
  ```

  ```bash npm theme={"dark"}
  npm install -g @duvoai/cli
  ```
</CodeGroup>

The curl script installs a standalone binary — no Node.js required. It supports macOS and Linux on x86\_64 and arm64. Override the install directory with `DUVO_INSTALL_DIR=$HOME/.local/bin` or pin a version with `DUVO_VERSION=<version>`.

<Note>The npm install requires Node.js 24 or newer. On Windows, use npm.</Note>

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

```bash theme={"dark"}
curl -fsSL https://duvo.ai/install-cli.sh | sh
```

Run `duvo --version` to confirm the install, and `duvo --help` to see every available command.

### Updating

Run `duvo update` to update the CLI in place. It detects how the CLI was installed and picks the right method automatically — npm installs run `npm install -g @duvoai/cli@latest`, while the standalone binary downloads the latest release, verifies its checksum, and replaces itself. Use `duvo update --check` to see whether a newer version is available without installing anything.

<Note>If the standalone binary lives in a directory you cannot write to (such as `/usr/local/bin`), `duvo update` stops with an error instead of updating. Rerun the installer, which requests sudo when needed: `curl -fsSL https://duvo.ai/install-cli.sh | sh`</Note>

## Quick start

<CodeGroup>
  ```bash curl (macOS / Linux) theme={"dark"}
  # 1. Install
  curl -fsSL https://duvo.ai/install-cli.sh | bash

  # 2. Sign in (opens your browser)
  duvo login

  # 3. List your Agents
  duvo agents list

  # 4. Start a Run
  duvo runs start --agent <agent-id>

  # 5. Check Run status
  duvo runs get <run-id>
  ```

  ```bash npm theme={"dark"}
  # 1. Install (requires Node.js 24+)
  npm install -g @duvoai/cli

  # 2. Sign in (opens your browser)
  duvo login

  # 3. List your Agents
  duvo agents list

  # 4. Start a Run
  duvo runs start --agent <agent-id>

  # 5. Check Run status
  duvo runs get <run-id>
  ```
</CodeGroup>

## Sign in

The CLI stores credentials as **named profiles**. Each profile holds either an OAuth session or an API key, so you can switch between teams or workspaces without re-entering credentials each time.

<Tabs>
  <Tab title="Duvo account (OAuth)">
    ```bash theme={"dark"}
    duvo login
    ```

    The CLI first prompts you for a profile name (for example, `acme` or `personal`), then opens your browser so you can sign in to Duvo. Once you approve, the CLI stores the OAuth session under that profile name. The first profile you add becomes the default.

    Pass `--name <profile>` to skip the prompt:

    ```bash theme={"dark"}
    duvo login --name acme
    ```
  </Tab>

  <Tab title="API key">
    Generate a key at [Your Profile → API keys](https://app.duvo.ai/settings/profile#api-keys) — pick **All teams I can access** for a key that works across your teams, or scope it to a single team. Users with the Manager role or above can also create and view a team's keys at [Team Settings → API keys](https://app.duvo.ai/settings/api-keys). Then:

    ```bash theme={"dark"}
    duvo login --api-key <key>
    ```

    Use API keys for service accounts, CI pipelines, and any non-interactive environment.
  </Tab>
</Tabs>

### Add another profile

Run `duvo login` again to repeat the browser sign-in and prompt for a new profile name. Pass `--api-key <key>` if you want the new profile to use an API key instead.

### Switch the default profile

```bash theme={"dark"}
duvo profiles use personal
```

If you omit the profile name, an interactive picker opens so you can arrow-key through your saved profiles:

```bash theme={"dark"}
duvo profiles use
```

### Use a different profile for a single command

```bash theme={"dark"}
duvo agents list --profile staging
```

`--profile <name>` works on every command and doesn't change your default.

### See who you're signed in as

```bash theme={"dark"}
duvo whoami
```

### Sign out

```bash theme={"dark"}
duvo logout                    # sign out of the active profile
duvo logout --name <profile>   # sign out of a specific profile
duvo logout --all              # sign out of every stored profile
```

`duvo logout` revokes the OAuth tokens server-side and removes the profile locally.

### Environment variables

For non-interactive use (CI, scripts), the CLI also reads:

| Variable       | Description                                    |
| -------------- | ---------------------------------------------- |
| `DUVO_API_KEY` | API key — bypasses the stored profile entirely |
| `DUVO_PROFILE` | Profile name to use instead of the default     |

## Output formats

By default every command prints a human-friendly table or summary. Add `--json` to any command for machine-readable output suitable for piping into `jq` or scripting:

```bash theme={"dark"}
duvo agents list --json | jq '.agents[] | {id, name}'
```

## Command groups

The CLI is organized by resource. Use these guides to dig into each area:

<CardGroup cols={2}>
  <Card title="Profiles and Teams" icon="users" href="/cli/profiles-and-teams">
    `duvo profiles`, `duvo team`, `duvo teams`
  </Card>

  <Card title="Managing Agents" icon="bot" href="/cli/managing-assignments">
    `duvo agents`, `duvo agent-folders`, `duvo revisions`
  </Card>

  <Card title="Starting Runs" icon="play" href="/cli/running-jobs">
    `duvo runs`, including live streaming and human-in-the-loop responses
  </Card>

  <Card title="Scheduling and Triggers" icon="calendar-clock" href="/cli/scheduling-and-triggers">
    `duvo agents schedules`, `duvo agents triggers`, `duvo agents case-triggers`
  </Card>

  <Card title="Managing Connections" icon="plug" href="/cli/managing-connections">
    `duvo connections`, `duvo integrations`, `duvo oauth`
  </Card>

  <Card title="Managing Files, Skills, and Plugins" icon="folder" href="/cli/managing-files-and-skills">
    `duvo files`, `duvo skills`, `duvo plugins`
  </Card>

  <Card title="Secrets and Logins" icon="key" href="/cli/secrets-and-logins">
    `duvo secrets`, `duvo credentials`, `duvo revision-secrets`, `duvo revision-logins`
  </Card>

  <Card title="Cases and Queues" icon="inbox" href="/cli/cases-and-queues">
    `duvo cases`, `duvo queues`, `duvo queue-labels`
  </Card>

  <Card title="Inspecting Clarity Processes" icon="workflow" href="/cli/clarity">
    `duvo clarity`
  </Card>

  <Card title="Scripting and CI/CD Patterns" icon="git-branch" href="/cli/scripting-and-ci">
    automation scripts, GitHub Actions, worked examples
  </Card>

  <Card title="Advanced commands" icon="settings" href="/cli/advanced">
    `duvo api`, `duvo sandboxes`, `duvo revision-integrations`
  </Card>
</CardGroup>

Each guide includes the exact commands, flags, and a few realistic examples.

## Tips

* Run `duvo <command> --help` to see every available flag for any command.
* Combine `--json` with `jq` to script complex workflows — for example, list all Runs that are waiting for human approval.
* Set `DUVO_PROFILE` in your shell config to default to a non-default profile per project.
* The CLI follows your Duvo team's permissions — if you can't see something in the UI, you can't see it via the CLI either.