> ## 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 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](/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 step-frames duvo clarity folders list duvo clarity capture-admin upload-document source.pdf duvo clarity capture-admin upload-image process-diagram.png duvo clarity import-artifact miro-export.svg duvo clarity invite-link create 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, document, or image. * **Current process snapshot** — the generated description of how the process works today. * **Automation proposal snapshot** — the generated proposal for how the process could be improved or automated. * **Proposal anchor** — the current process snapshot that an automation 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 automation 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. Persisted inclusion fields are available in both output formats. JSON uses `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`: ```bash theme={"dark"} duvo clarity captures --json --include-transcripts duvo clarity capture --json --include-transcripts ``` For Process Landscape captures, excluded captures are hidden by default because they are not generation inputs. Include them when auditing capture quality: ```bash theme={"dark"} duvo clarity landscape captures --org --include-excluded --json ``` Landscape capture output differs from process capture output: the landscape endpoint emits snake\_case keys and the CLI prints them unchanged, so JSON output uses `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 ```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. ## Resolve step screenshots Use `step-frames` to get one representative screenshare image for each step in a Current Process snapshot: ```bash theme={"dark"} duvo clarity step-frames duvo clarity step-frames --snapshot latest duvo clarity step-frames --step --step duvo clarity step-frames --step --window 5 duvo clarity step-frames --size thumb duvo clarity step-frames --json ``` The command selects the live snapshot by default. `--snapshot` also accepts `latest` or an exact snapshot ID. Repeat `--step` to limit the response to specific steps, up to 100 IDs. The output shows whether each image came from explicit step evidence or the nearest screenshare frame based on transcript timing. Review images selected from transcript timing before you use them in a published procedure. Signed download URLs are short-lived, so download each image when you receive the response. When access signing is unavailable, the frame is still listed with its timestamp but without a download URL. When the selected image does not show the step (for example a screen caught mid-transition), pass `--window ` (1–5) to also receive up to `n` neighbouring frames on each side of the selection as candidates. Each candidate carries its `offset` from the selected frame (`-1` is the frame just before it) and its own download URL, so an agent or reviewer can pick a better frame from the same recording. Pass `--size thumb` to link 768px-wide copies instead of the full 1920px frames. Thumbnails are derived on first request and stored next to the originals; they are cheaper to download and to inspect, so use them to check which frame shows a step and fetch the full size for the final document. If a thumbnail cannot be derived, the full frame is linked instead. ## 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. 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 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 create --name "Invoice approval" 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 [--proposal-id ] duvo clarity update --name "Invoice approval" --visibility restricted duvo clarity update --guidance "Escalate invoices over EUR 10,000" duvo clarity update --clear-guidance duvo clarity update --interviews independent duvo clarity update --complete duvo clarity duplicate duvo clarity delete --yes ``` `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 automation 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. With CLI 1.68.0 and a backend supporting plural exceptions, saves preserve each step's `exceptions` array, including custom IDs, handling, and frequency (`rare`, `occasional`, `frequent`, or `null`). Older `exception`/`handling` input is also accepted and normalized. Do not combine the old fields with `exceptions` on the same step. Snapshot reads, saves, and promotions use the existing endpoints and return V2 data with exception arrays. Update scripts and MCP clients to read both V1 and V2 before enabling V2 writes; installing the CLI alone does not update other clients. `update --interviews` sets the process's interview mode. Pass `independent` so each interview starts fresh, without context from earlier interviews. Pass `context-aware` so interviews build on what Clarity already knows about the process. The change applies to interviews that start afterward. If the Duvo server doesn't support the setting yet, the CLI exits with an error and leaves the process unchanged. `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, interview mode 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: ```bash theme={"dark"} duvo clarity landscape get --org --json duvo clarity landscape create-area --org --name "Finance" duvo clarity landscape propose-process --org --name "Invoice approval" --materialization-mode proposal duvo clarity landscape add-process --org --parent duvo clarity landscape rename-node --org --name "Finance operations" duvo clarity landscape move-node --org --parent duvo clarity landscape reorder-areas --org --area --area duvo clarity landscape delete-node --org --yes duvo clarity landscape accept-node --org duvo clarity landscape decline-node --org --yes duvo clarity landscape assign-team --org --team duvo clarity landscape organize --org ``` `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. Review generated suggestions and assign the resulting capture work: ```bash theme={"dark"} duvo clarity landscape suggestions accept-team duvo clarity landscape suggestions dismiss-team duvo clarity landscape suggestions accept-capture duvo clarity landscape suggestions dismiss-capture duvo clarity landscape suggestions assign-capture --user duvo clarity landscape suggestions assign-capture --unassign ``` Suggestion commands resolve the organization from the node, so they do not take `--org`. Manage the people involved in one process or several processes: ```bash theme={"dark"} duvo clarity landscape node-people --org duvo clarity landscape add-person --org --name "Alex" --role "Approver" duvo clarity landscape add-person --org --email "alex@example.com" --role "Approver" duvo clarity landscape update-person --org --clear-role duvo clarity landscape remove-person --org --yes duvo clarity landscape batch-people --org --input assignments.json --json ``` Supplying an email grants that person process access and sends an invitation. `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. ```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. ## Organize the Process Library Manage the same team folders used by the Clarity process library: ```bash theme={"dark"} duvo clarity folders list duvo clarity folders create --name "Finance" duvo clarity folders update --name "Finance operations" duvo clarity folders reorder --folder --folder duvo clarity folders move-processes --process --folder duvo clarity folders move-processes --process --to-root duvo clarity folders setup-from-landscape duvo clarity folders file-suggested duvo clarity folders delete --yes ``` `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 ```bash theme={"dark"} duvo clarity guidance create --content "Focus on approval controls." duvo clarity guidance update --content-file guidance.md duvo clarity settings get duvo clarity settings update --team-size 80 --average-hourly-rate 55 duvo clarity settings update --language en --enable-email-reports --include-summary duvo clarity sharing get duvo clarity sharing set --enabled --proposal-enabled duvo clarity sharing set --disabled duvo clarity members list duvo clarity members remove --yes ``` Guidance is the transformation brief used when Clarity generates recommendations. Team settings also support company name, industry, annual revenue, email-report capture inclusion, and explicit `--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: ```bash theme={"dark"} duvo clarity capture-admin upload-document source.pdf duvo clarity capture-admin upload-video walkthrough.mp4 duvo clarity capture-admin upload-image process-diagram.png duvo clarity capture-admin invite-notetaker \ --meeting-url "https://meet.google.com/abc-defg-hij" duvo clarity capture-admin delete --yes ``` Use `--extra-capture-request-id ` on an upload or meeting notetaker to satisfy a specific follow-up request. Process document captures can be PDF, Word (.docx), TXT, Markdown, BPMN, XLSX, or CSV files up to 25 MB; interview document uploads accept PDF, Word (.docx), TXT, Markdown, or BPMN. Images can be still PNG, JPEG, WebP, or SVG files up to 25 MB, 16,384 pixels per side, and 50 megapixels. For SVG files, the 50-megapixel limit applies to all embedded images combined. Duvo converts SVG files to safe PNG images before reading them. Animated images aren't supported. If image processing is busy, try the upload again in a few minutes. 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. 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 ` (or `DUVO_ORG_ID`). Team interview commands use the selected team. Landscape-node interviews are scoped to both the organization and node. ```bash theme={"dark"} duvo clarity interviews org list --org duvo clarity interviews org get --org duvo clarity interviews org rename --org --title "Finance discovery" duvo clarity interviews org finalize --org duvo clarity interviews org upload-document discovery.pdf --org duvo clarity interviews org invite-notetaker --org \ --meeting-url "https://zoom.us/j/123456789" duvo clarity interviews org delete --org --yes duvo clarity interviews node list --org duvo clarity interviews node delete --org --yes duvo clarity interviews team list duvo clarity interviews team upload-document discovery.pdf duvo clarity interviews team delete --yes ``` List commands support `--limit` and `--offset`. Organization lists can use `--scope organization` or `--scope team`. Upload limits match process document captures; supported types are PDF, Word (.docx), TXT, Markdown, or BPMN — XLSX and CSV are process-capture only. ## 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`. ## Manage Interview Invite Links Read, create, revoke, inspect, or accept an interview invite link: ```bash theme={"dark"} duvo clarity invite-link get duvo clarity invite-link create duvo clarity invite-link delete --yes duvo clarity invite-link inspect duvo clarity invite-link accept ``` `duvo clarity create-invite-link ` 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. ## Invite People to Record Interviews Invite people to record an interview about a process and email them, then follow their progress: ```bash theme={"dark"} duvo clarity interview-invites send \ --invitee alex@example.com:"Alex Morgan" \ --include-process-people \ --message "Ten minutes on how you approve invoices would help a lot." duvo clarity interview-invites list --limit 50 --offset 0 duvo invite delete ``` `send` takes at most 25 unique people per call and creates the same invitations as the Invite dialog, so someone already invited gets their invitation again rather than a second one. When your workspace has account-free interview links turned on, people without a Duvo account get a link that opens the interview directly; everyone else gets the normal invitation that asks them to sign in. The output shows which one each person got. `--message` is plain text, up to 500 characters. Revoke a pending invitation with `duvo invite delete`, which also ends any account-free link it sent. ## Export and Portfolio Workflows ```bash theme={"dark"} duvo clarity exports start \ --connection-instance \ --bpmn-file process.bpmn duvo clarity exports list duvo clarity exports get duvo clarity portfolio get duvo clarity portfolio generate duvo clarity upgrade ``` SAP Signavio export accepts a BPMN XML file or `--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 get` and `portfolio generate` require the Manager role or above on the team, or an organization Admin role; other roles receive a not-found response. `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. ```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 duvo clarity artifact-chat-stop duvo clarity artifact-chat-delete --yes ``` Ask Duvo uses its reviewed patch-draft workflow for free-form artifact edits. The lower-level send-message and patch-decision commands remain available to CLI clients, while Ask Duvo exposes the durable conversation list, message history, stop, and delete controls. ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.