Skip to main content
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.

​
Quick start

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

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

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 the live snapshot by default.
You can select a different snapshot with: Examples:
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

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:

​
Trace evidence

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:
For scripts, use --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
Use 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.
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.
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:
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:
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.

​
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:
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

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.

​
Audit source coverage

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.