@duvoai/cli 1.5.0 → 1.6.0

package/guides/duvo.md

@@ -0,0 +1,116 @@
+---
+name: duvo
+description: Core usage guide for the Duvo CLI — auth, profiles, teams, global flags, JSON output, and the command map. Start here before guessing commands from flag docs alone.
+---
+
+# Duvo CLI — Core Usage
+
+The `duvo` CLI is a scriptable client for the Duvo public API — a single
+`duvo` binary with resource-grouped subcommands.
+
+If you are an AI agent driving this CLI, read this guide first, then load a
+specialized guide with `duvo guide get <name>` (see `duvo guide list`).
+
+## First moves
+
+```bash
+duvo --help            # full command map
+duvo whoami            # who am I, which team, which auth type
+duvo guide list        # bundled guides shipped with this CLI version
+```
+
+## Authentication
+
+`duvo login` signs you in via **OAuth** (opens a browser) by default, or
+stores a team **API key** with `--api-key`. Either way the credential is
+saved as a **named profile** — one per login — the same shape as AWS CLI
+profiles, so you can switch between teams.
+
+```bash
+duvo login [--name <profile>]              # OAuth browser sign-in (default)
+duvo login --api-key <key> [--name <p>]    # store an API key instead
+duvo logout [--name <profile>]             # remove a profile
+```
+
+Non-interactive auth (CI, agents): set `DUVO_API_KEY` and skip `login`
+entirely. The key's team is fixed, so team-scoped commands resolve
+automatically.
+
+Precedence:
+
+- **Profile**: `--profile <name>` > `DUVO_PROFILE` env > default profile.
+- **Credential**: `DUVO_API_KEY` env (always an API key) > the selected
+  profile's stored credential (OAuth token or API key).
+- **Base URL**: `DUVO_API_BASE_URL` env > profile's `apiBaseUrl` >
+  `https://api.duvo.ai`. The value is an origin only (no path prefix).
+
+## Teams
+
+Most commands act on a single team. Resolve order: `--team <id>` flag >
+`DUVO_TEAM_ID` env > the profile's default team. API-key profiles are pinned
+to the key's team. Check the active team with `duvo whoami`.
+
+## Global flags
+
+| Flag               | Effect                                                 |
+| ------------------ | ------------------------------------------------------ |
+| `--profile <name>` | use a specific profile for this invocation             |
+| `--team <id>`      | use a specific team for this invocation                |
+| `--json`           | (per command) raw JSON to stdout — the stable contract |
+
+## Output modes
+
+- **Single resource** → a labelled key/value block.
+- **Collection** → a fixed-column table with a trailing `Showing N` summary.
+- **`--json`** → raw API JSON, never coloured or truncated. Pipe it to `jq`.
+  This is the stable contract; table/text formatting can change, JSON will not.
+
+Prefer `--json` whenever you parse output programmatically.
+
+## Exit codes
+
+`0` success · `1` generic error · `2` auth error (missing/invalid key or
+unknown profile) · `3` not found · `4` forbidden.
+
+## Command map
+
+Duvo UI labels and CLI/API names refer to the same concepts:
+
+- **Assignment** (UI) = an agent → the `agents` command.
+- **Job** (UI) = a run → the `runs` command.
+- **Connections** (UI) = integrations → the `connections` / `integrations` commands.
+- **Files** (UI) = knowledge base → the `files` command.
+- **MCP**: Connections are surfaced to an Assignment as **MCP** tool servers;
+  a custom MCP server URL is itself one kind of Connection.
+
+```text
+duvo login | logout | whoami | profiles    # auth & local config
+duvo agents | agent-folders | builds        # Assignments and their revisions
+duvo runs | queues | queue-labels | cases   # Jobs and work queues
+duvo connections | integrations | oauth     # Connections
+duvo files | skills | plugins               # Files, Skills, plugins
+duvo secrets | credentials                  # secrets & logins
+duvo team | teams | clarity | sandboxes     # team, Clarity, sandboxes
+duvo api <METHOD> <path>                     # low-level escape hatch
+duvo guide                                   # these bundled guides
+```
+
+## Escape hatch — `duvo api`
+
+Any public endpoint is reachable before it has a dedicated command, modelled
+on `gh api`:
+
+```bash
+duvo api GET /v1/agents -F limit=20 -F offset=0
+duvo api POST /v1/agents -f name="Ops bot"
+cat body.json | duvo api POST /v1/agents --input -
+```
+
+`-f key=value` always sends a string; `-F key=value` parses booleans, numbers,
+JSON null, or `@file`. Run `duvo api --help` for the full flag set.
+
+## Discoverability
+
+Every command and subcommand supports `--help`. When in doubt, run
+`duvo <group> --help` rather than guessing flags — and prefer these bundled
+guides, which are always matched to the installed CLI version.

package/guides/runs.md

@@ -0,0 +1,76 @@
+---
+name: runs
+description: Start, watch, and steer Jobs (runs) from the CLI — starting work on an Assignment, reading messages, responding to human-in-the-loop requests, and stopping a Job.
+---
+
+# Working with Jobs (runs)
+
+In Duvo, a **Job** is a single execution of an **Assignment**. The CLI and API
+call these `run` and `agent` respectively. This guide covers the Job
+lifecycle. For the basics (auth, teams, `--json`) read `duvo guide get duvo`
+first.
+
+## Start work
+
+```bash
+duvo runs start --agent <agent-id> [--follow] [--json]
+```
+
+`--agent` is the Assignment (agent) ID — list candidates with
+`duvo agents list`. The response includes the new Job ID; capture it with
+`--json` and `jq -r '.id'` for scripting. Pass `--follow` to stream the Job's
+messages live until it completes, instead of just printing the new Job ID.
+
+## Inspect a Job
+
+```bash
+duvo runs get <run-id>                # status and metadata
+duvo runs messages <run-id>           # full message history
+duvo runs messages <run-id> --follow  # poll for new messages until it finishes
+```
+
+Use `--json` on `get` or `messages` to parse the result. Job status tells you whether the
+Job is still working, waiting on a human, finished, or stopped.
+
+## Talk to a running Job
+
+```bash
+duvo runs send-message <run-id> --message "Use the EU supplier list"
+```
+
+This appends a user message to an in-flight Job — the way to add context or
+correct course without restarting.
+
+## Human-in-the-loop requests
+
+When a Job needs a human decision it pauses with a pending request. Respond
+with one of:
+
+```bash
+duvo runs respond <run-id> --approve
+duvo runs respond <run-id> --deny
+duvo runs respond <run-id> --answer question=answer
+```
+
+The request ID defaults to the Job's current pending request, so you usually
+only pass the Job ID. Pass an explicit request ID as the second positional
+argument when disambiguating.
+
+## Stop a Job
+
+```bash
+duvo runs stop <run-id>          # destructive — prompts unless --yes
+```
+
+Stopping interrupts the Job and pauses its sandbox. In non-interactive
+contexts pass `--yes`/`-y`; the CLI refuses to infer consent from piped stdin.
+
+## A minimal scripted loop
+
+```bash
+RUN_ID=$(duvo runs start --agent "$AGENT_ID" --json | jq -r '.id')
+duvo runs get "$RUN_ID" --json | jq -r '.status'
+# ...poll, respond to human requests, or send-message as needed...
+```
+
+Always prefer `--json` in scripts — it is the stable output contract.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@duvoai/cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Command-line interface for the Duvo public API",
   "bin": {
     "duvo": "./dist/bin/duvo.js"
   },
   "files": [
     "dist",
+    "guides",
     "README.md"
   ],
   "type": "module",