@duvoai/cli 0.9.0 → 1.1.0

package/README.md

@@ -32,8 +32,8 @@ duvo agents create
 # ...or create one non-interactively with flags
 duvo agents create --name "My agent" --input "What this agent should do"
 
-# 4. Kick off a run
-duvo runs start --agent <agent-id>
+# 4. Kick off a run and watch it complete
+duvo runs start --agent <agent-id> --follow
 ```
 
 Grab an API key from your team settings: <https://app.duvo.ai/settings/api-keys>.
@@ -51,6 +51,97 @@ 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
+
+```bash
+# 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).
+
+```bash
+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`.
+
+```bash
+# 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.
+
+```bash
+# 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 case queues
+
+```bash
+# Create a queue
+duvo queues create --name "support-tickets"
+
+# 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
+
+# Bulk delegate pending cases to an agent
+duvo cases bulk-delegate --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:
+
+```bash
+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.
@@ -154,7 +245,7 @@ Default output is summary-first and compact. JSON output also includes a compact
 | `duvo oauth mcp probe <url>`                                                         | Probe an MCP server URL and list tools it exposes (`--header KEY=VALUE` repeatable).    |
 | `duvo oauth mcp authorize --url <url> --name <n>`                                    | Start an OAuth-based connection with a remote MCP server (DCR). Prints the auth URL.    |
 | `duvo oauth mcp check --url <url>`                                                   | Probe an MCP server URL for OAuth Dynamic Client Registration support.                  |
-| `duvo revision-integrations list`                                                    | List integrations attached to a revision                                                |
+| `duvo revision-integrations list`                                                    | List integrations attached to a revision (shows SLOT ID and INTEGRATION ID columns)     |
 | `duvo revision-integrations attach`                                                  | Attach one or more integrations to a revision                                           |
 | `duvo revision-integrations remove <integration-id>`                                 | Remove an integration slot from a revision                                              |
 | `duvo revision-integrations connections list`                                        | List your pinned connections for a revision's integration slot                          |
@@ -202,6 +293,35 @@ Run `duvo <command> --help` for full flags on any command.
 
 ## Details
 
+### `runs messages --follow` / `runs start --follow`
+
+Both commands accept `--follow` to poll for new messages until the run
+reaches a terminal state:
+
+| State       | Meaning                                |
+| ----------- | -------------------------------------- |
+| `completed` | Run finished successfully              |
+| `failed`    | Run encountered an unrecoverable error |
+| `stopped`   | Run was stopped manually               |
+| `error`     | Run terminated with a system error     |
+
+The default poll interval is 2 s. The `--offset <n>` flag lets you resume
+from a specific message position in `runs messages --follow`.
+
+### `revision-integrations connections` and `--integration`
+
+The `--integration <id>` flag on `connections list`, `connections pin`, and
+`connections unpin` accepts either identifier from `revision-integrations
+list` — the **SLOT ID** (`id` field of the integration slot record) or the
+**INTEGRATION ID** (catalog ID) in the same table.
+
+```text
+INTEGRATION ID                        TYPE   NAME   SLOT ID   CREATED
+22222222-2222-2222-2222-222222222222  gmail  Gmail  slot-1    2026-04-15…
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^                ^^^^^^^
+either one works
+```
+
 ### `cases create --from-file`
 
 Pass a JSON file containing a single case object or an array of up to 100 case objects.