> ## 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. # Clarity CLI > Use the Duvo CLI to inspect, update, and manage Clarity processes from your terminal. Use `duvo clarity` to inspect and update Clarity processes from a terminal. The CLI can find processes, inspect generated documentation, compare versions, review evidence, import Miro exports, create interview invite links, and call public Clarity write routes. For an overview of Clarity itself, see [Clarity](/user-guide/assignment-features/clarity). ## Quick start ```bash theme={"dark"} duvo clarity search "invoice" --limit 5 duvo clarity overview duvo clarity versions duvo clarity compare duvo clarity gaps duvo clarity evidence duvo clarity import-artifact miro-export.svg duvo clarity create-invite-link duvo clarity export > clarity-brief.md ``` Most commands print a compact human-readable summary by default. Add `--json` when you want structured output for scripts or an AI assistant. Add `--include-transcripts` only when you need capture transcripts or media URLs in JSON output; compact output omits them by default. ## Important terms * **Process** — a Clarity process created in the Duvo web app. * **Capture** — a source attached to a process, such as an interview, video recording, or uploaded AOP. * **Current process snapshot** — the generated description of how the process works today. * **Transformation proposal snapshot** — the generated proposal for how the process could be improved or automated. * **Proposal anchor** — the current process snapshot that a transformation proposal was generated from. If the anchor does not match the selected current process snapshot, compare output warns you. * **Evidence citation** — a stable citation ID that points from a generated step back to supporting capture evidence. * **Extra capture request** — a request for more source material when Clarity cannot confidently fill a gap. * **Readiness** — Clarity's per-step signal for how ready a proposed step is for automation. * **Facets** — structured cost, risk, lineage, and automation slices built for AI assistants and scripts. ## Find a process ```bash theme={"dark"} duvo clarity list duvo clarity list --status complete --limit 20 duvo clarity list --process-version 2 --csv duvo clarity search "purchase order" --json ``` Use `--status` to filter by lifecycle status and `--process-version` to separate legacy v1 processes from newer v2 processes. Use `--csv` when you want a process inventory in a spreadsheet. ## Inspect the selected context ```bash theme={"dark"} duvo clarity overview duvo clarity status duvo clarity export duvo clarity export --json ``` `overview` is the best first command for a process. It shows process health, selected versions, capture counts, warnings, and recommended next commands. `status` focuses on lifecycle state and generation health. `export` prints a Markdown brief by default. Use it when you want to save or share the compact process context: ```bash theme={"dark"} duvo clarity export > process-brief.md ``` ## Work with versions Clarity v2 stores generated content as snapshots. Most v2 commands select the `live` snapshot by default. ```bash theme={"dark"} duvo clarity versions duvo clarity current duvo clarity proposal duvo clarity compare ``` You can select a different snapshot with: | Selector | Meaning | | -------- | ------------------------------------------------- | | `live` | The snapshot currently shown in the app | | `latest` | The newest snapshot, even if it is not live | | `` | An exact snapshot ID from `duvo clarity versions` | Examples: ```bash theme={"dark"} duvo clarity current --snapshot latest duvo clarity proposal --snapshot duvo clarity compare \ --current \ --proposal ``` Use `compare` when an assistant needs to understand what changed between the current process and the transformation proposal. It also shows whether the proposal anchor matches the selected current process. ## Review captures ```bash theme={"dark"} duvo clarity captures duvo clarity captures --csv duvo clarity captures --json duvo clarity capture

--json ``` By default, capture output is compact for routine inspection: it includes metadata and usability signals, but not full transcripts or media URLs. When you need the full capture text in JSON output, add `--include-transcripts`: ```bash theme={"dark"} duvo clarity captures --json --include-transcripts duvo clarity capture

--json --include-transcripts ``` ## Trace evidence ```bash theme={"dark"} duvo clarity evidence duvo clarity evidence --json duvo clarity evidence --citation ``` Use `evidence` when you need to verify where a generated step came from. The command prints citation IDs for each step. Resolve one citation ID to see the supporting source: ```bash theme={"dark"} duvo clarity evidence --citation citation:::1 ``` For scripts, use `--json` and require downstream outputs to cite only IDs returned by this command. ## Find gaps and automation candidates ```bash theme={"dark"} duvo clarity gaps duvo clarity readiness duvo clarity facets ``` `gaps` groups missing information, open questions, assumptions, and extra capture requests by proposed step. `readiness` summarizes which proposed steps are high, medium, or low readiness for automation. `facets` returns a structured view of: * Cost signals * Risk signals * Current and proposal step lineage * Evidence coverage * Automation readiness * Warnings and next commands Use `duvo clarity facets --json` when an AI assistant needs a compact structured input before deciding which deeper command to call next. ## Update a Process Use write commands when you want to generate, promote, revert, postprocess, or assign follow-up capture work for Clarity v2 snapshots from a script. ```bash theme={"dark"} duvo clarity generate-current-process duvo clarity generate-transformation-proposal \ --current-process-id duvo clarity generate-transformation-proposal \ --regenerate-from duvo clarity save-current-process \ --baseline-snapshot-id \ --steps-file edited-current-steps.json duvo clarity save-transformation-proposal \ --baseline-snapshot-id \ --steps-file edited-proposal-steps.json duvo clarity promote-current-process

duvo clarity promote-transformation-proposal

duvo clarity revert-current-process

duvo clarity revert-transformation-proposal

duvo clarity postprocess current_process duvo clarity postprocess transformation_proposal duvo clarity assign-extra-capture-request

\ --user-id duvo clarity stop-current-process duvo clarity stop-transformation-proposal duvo clarity build-automation ``` `generate-transformation-proposal` accepts either `--current-process-id` or `--regenerate-from`, not both. Use `--json` on any write command when you need the raw API response. `save-current-process` and `save-transformation-proposal` read edited steps from a JSON file. The file can contain either the step array directly or an object with a `steps` array. `assign-extra-capture-request` assigns a proposal gap to a team member. Omit `--user-id` to unassign the request. ## Manage Process Tags Tag processes with organization-wide labels to group and filter them across the landscape. A tag is a value plus an optional color hue. ```bash theme={"dark"} duvo clarity process-labels list --org duvo clarity process-labels list --org --search "fin" --limit 20 --offset 20 duvo clarity process-labels create --org --value "Finance" --color-hue 215 duvo clarity process-labels update --org --value "Ops" duvo clarity process-labels delete --org --yes duvo clarity process-labels list-process --process duvo clarity process-labels available --process --search "fin" duvo clarity process-labels assign --process --label duvo clarity process-labels unlink --process --label ``` Set `DUVO_ORG_ID` to skip `--org` on palette commands. Repeat `--label` to assign or unlink several tags at once, and use `--json` on any command for the raw API response. `list` and `available` return one page at a time (default 50 tags, maximum 100) and print how many of the total matched. Use `--limit` and `--offset` to page through larger palettes, and `--search` to filter tags by value on the server. Creating, updating, and deleting tags requires a manager role on a team in the organization (or an organization admin role); assigning or unlinking tags requires a manager role on the process's own team (or an organization admin role). Listing tags is open to all organization members. ## Import Miro Exports Import SVG, XML, PNG, or JPEG exports from Miro into a Clarity process: ```bash theme={"dark"} duvo clarity import-artifact miro-map.svg duvo clarity import-artifact miro-map.xml \ --extra-capture-request-id ``` `import-artifact` creates a signed upload URL, uploads the local file, and completes the import. For custom upload workflows, use `duvo api` against the public artifact-import endpoints directly. Supported content types are `image/svg+xml`, `application/xml`, `text/xml`, `image/png`, and `image/jpeg`. ## Invite Someone to an Interview Create or regenerate an interview invite link for a process: ```bash theme={"dark"} duvo clarity create-invite-link ``` The command prints the link and creation metadata. Send the URL to the person you want to interview. ## Use Artifact Chat If Artifact Chat is available for your team, use these commands to ask Clarity to modify generated artifacts, answer review questions, and accept or decline proposed patches. ```bash theme={"dark"} duvo clarity artifact-chat-conversations \ --snapshot-kind current_process duvo clarity artifact-chat-messages

duvo clarity send-artifact-chat-message \ --snapshot-kind current_process \ --baseline-snapshot-id \ --message "Make the first step more specific." duvo clarity send-artifact-chat-message \ --conversation-id \ --snapshot-kind current_process \ --baseline-snapshot-id \ --answer question-id="Yes, this applies to all regions." duvo clarity decide-artifact-chat-patch

--accept duvo clarity decide-artifact-chat-patch

--decline ``` ## Check the environment ```bash theme={"dark"} duvo clarity doctor duvo clarity doctor duvo clarity tools ``` `doctor` checks authentication, API reachability, available commands, and optional process-level context health. `tools` lists the Clarity tool map used by the CLI, including each command and the underlying public API endpoint. It is useful when an assistant needs to decide which `duvo clarity` command can answer a question or perform a write. ## Legacy v1 processes The CLI can still read legacy v1 Clarity processes through: ```bash theme={"dark"} duvo clarity overview duvo clarity status duvo clarity captures duvo clarity capture

duvo clarity export ``` V2-only commands such as `versions`, `current`, `proposal`, `compare`, `gaps`, `evidence`, `readiness`, and `facets` require a v2 process. If you run them against a v1 process, the CLI explains that the command is unavailable for that process version. ## Common workflows The examples below use a fictional Invoice Approval process with the ID `b3f1c2d4-1a2b-4c3d-8e9f-001122334455`. Swap in a real ID from `duvo clarity list` or `duvo clarity search`. ### Gather context for an AI assistant ```bash theme={"dark"} duvo clarity search "invoice approval" --json duvo clarity overview b3f1c2d4-1a2b-4c3d-8e9f-001122334455 --json duvo clarity facets b3f1c2d4-1a2b-4c3d-8e9f-001122334455 --json duvo clarity evidence b3f1c2d4-1a2b-4c3d-8e9f-001122334455 --json ``` `search` resolves the process ID, `overview` orients the assistant (health, selected snapshots, recommended next commands), `facets` adds structured cost, risk, and automation slices, and `evidence` returns citation IDs the assistant can quote so its reasoning stays grounded in real sources. ### Produce a brief for a stakeholder ```bash theme={"dark"} duvo clarity export b3f1c2d4-1a2b-4c3d-8e9f-001122334455 > invoice-approval-brief.md duvo clarity gaps b3f1c2d4-1a2b-4c3d-8e9f-001122334455 >> invoice-approval-brief.md duvo clarity readiness b3f1c2d4-1a2b-4c3d-8e9f-001122334455 >> invoice-approval-brief.md ``` `export` writes the process overview as Markdown; appending `gaps` and `readiness` rounds the brief out with what is still missing and how automation-ready each proposed step is. ### Audit source coverage ```bash theme={"dark"} duvo clarity captures b3f1c2d4-1a2b-4c3d-8e9f-001122334455 --csv > captures.csv duvo clarity evidence b3f1c2d4-1a2b-4c3d-8e9f-001122334455 --json > evidence.json duvo clarity gaps b3f1c2d4-1a2b-4c3d-8e9f-001122334455 --json > gaps.json ``` Cross-reference the three files to see which captures were usable, which steps have citations, and where Clarity requested more evidence before you trust or automate the process.