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.
Quick start
--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 SOP.
- 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
--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
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:
Work with versions
Clarity v2 stores generated content as snapshots. Most v2 commands select thelive snapshot by default.
| Selector | Meaning |
|---|---|
live | The snapshot currently shown in the app |
latest | The newest snapshot, even if it is not live |
<id> | An exact snapshot ID from duvo clarity versions |
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
--include-transcripts:
Trace evidence
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:
--json and require downstream outputs to cite only IDs returned by this command.
Find gaps and automation candidates
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
duvo clarity facets <process-id> --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.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.
assign-extra-capture-request assigns a proposal gap to a team member. Omit --user-id to unassign the request.
Import Miro Exports
Import SVG, XML, PNG, or JPEG exports from Miro into a Clarity process: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:Use Artifact Chat
Artifact-chat workflows do not have a dedicated high-levelduvo clarity command. Use duvo api against the public artifact-chat routes when you need to ask Clarity to modify generated artifacts, answer review questions, or accept or decline proposed patches.
Check the environment
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: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 IDb3f1c2d4-1a2b-4c3d-8e9f-001122334455. Swap in a real ID from duvo clarity list or duvo clarity search.
Gather context for an AI assistant
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
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.