duvo clarity to inspect and manage Clarity from a terminal. The CLI covers the durable actions available in the web app, including process generation, folders, captures, interviews, sharing, exports, portfolio intelligence, and organization-level Process Landscape administration.
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, document, or image.
- 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.
Examples:
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
usabilityStatus, usabilityReason, usabilitySource, and usabilityConfidence; CSV uses the usability_status, usability_reason, usability_source, and usability_confidence headers. Captures with an excluded status stay readable but are not used in future Clarity analysis.
When you need the full capture text in JSON output, add
--include-transcripts:usability_status, usability_reason, usability_source, and usability_confidence (the landscape command has no CSV mode). The same inclusion fields and AI-generated reason are returned. Add --include-transcripts only when the full transcript is also required.
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. When Duvo has nominated someone from the process roster to fill a gap in a follow-up interview, the request also shows the suggested interviewee and a short reason.
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.build-automation builds from the process’s live transformation proposal. Pass --proposal-id to build from a specific proposal snapshot instead.
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.
The update, duplicate, and delete lifecycle commands support both Clarity v1 and v2 processes. The snapshot, post-processing, and Automation commands in this section are Clarity v2 only.
Only one generation or post-processing run can be active for a process at a time. Repeating build-automation for the same proposal returns its existing Workflow Builder run; building from a different proposal creates a new run.
If the resolved proposal is still being generated, build-automation returns a conflict. Wait for generation to finish, then run the command again.
create, process-name updates, guidance updates, and snapshot save, promote, and revert commands require the Builder role or above. Builders can apply these content edits to any process they can access in their team. Changing --visibility requires the process creator or a Manager, and --complete requires a process in review and the Manager role.
delete requires the process creator or a Manager. It soft-deletes the process from normal product views and refuses while capture analysis is active, so a Builder can delete their own process but not another Builder’s process.
Ask Duvo can perform the same durable process actions: start or stop generation, save, promote, or revert versions, run post-processing, import a supported artifact, build an Automation, and update, duplicate, or delete a process. Ask Duvo uses your existing Clarity permissions, so it cannot perform an action that the web app would deny for your account.
Curate the Process Landscape
Read the organization-wide Process Landscape, then make durable changes to its areas, processes, suggestions, capture requests, and people:propose-process creates a real process by default when --team is set. The explicit --materialization-mode proposal option requires Manager-or-above authority for that team. Builders create real processes through the default mode. Chat-scoped discovery agents can submit proposals for their pinned team.
A team-scoped API key can assign a process only to the key’s team. Use user-scoped credentials for an authorized cross-team move.
Most landscape writes take effect immediately.
organize starts a background pass across all eligible unfiled processes in the Organization; HTTP 202 confirms submission, changes appear progressively, and there is no dry run or one-click undo. Re-read the landscape before reporting its results. delete-node and decline-node prompt before making destructive changes; pass --yes only for intentional non-interactive use. reorder-areas requires every sibling exactly once. decline-node removes proposed descendants, while real processes below the proposal move to Unsorted.--org.
Manage the people involved in one process or several processes:
batch-people accepts the public API request body from a file or stdin (--input -) and reports every assignment separately.
Ask Duvo can perform the same actions with the user’s organization and team permissions. It re-reads the current landscape before writing. organize runs asynchronously, so Ask Duvo starts the pass and must re-read the landscape to observe changes; batch people operations return an outcome for every requested assignment.
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.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.
Organize the Process Library
Manage the same team folders used by the Clarity process library:reorder requires every folder exactly once. Deleting a folder keeps its processes and moves them to Unfiled. setup-from-landscape creates any missing team folders linked to the Process Landscape; file-suggested files visible Unfiled processes into those linked folders.
Manage Settings, Guidance, Sharing, and Access
--clear-* options. Public sharing is available only where the process state and the caller’s role allow it. Removing a member revokes accepted process access; it does not delete the user.
Add and Manage Captures
Create durable process captures without opening the browser:--extra-capture-request-id <id> on an upload, phone interview, or meeting notetaker to satisfy a specific follow-up request. Documents can be PDF, TXT, Markdown, or BPMN files up to 25 MB. Images can be PNG, JPEG, or WebP files up to 25 MB. Videos can be MP4, MOV, WebM, MPEG, MPG, AVI, FLV, WMV, 3GP, or 3GPP files up to 2 GB. The CLI streams files to the signed upload URL instead of loading them fully into memory.
Phone calls and meeting notetakers create durable capture work, but the CLI does not expose browser-bound recording sessions, live audio transport, media chunking, or internal ingestion callbacks.
Manage Interview Libraries
Organization interviews require an organization role and--org <org-id> (or DUVO_ORG_ID). Team interview commands use the selected team. Landscape-node interviews are scoped to both the organization and node.
--limit and --offset. Organization lists can use --scope organization or --scope team. Upload limits and supported document types match process document captures.
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.
Manage Interview Invite Links
Read, create, revoke, inspect, or accept an interview invite link:duvo clarity create-invite-link <process-id> remains available as a compatibility alias. Inspecting a token does not accept it. Acceptance requires a signed-in user whose verified email matches the invitation.
Export and Portfolio Workflows
--bpmn-file - for stdin, up to 5 MB. Export and portfolio list/generation commands use the selected team; exports get verifies access to the requested export. portfolio generate starts background generation, and upgrade converts an eligible legacy process to Clarity v2.
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: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.