---
url: /reference/cli-commands.md
description: Every dutygraph CLI command with examples and the rules it follows.
---

# CLI commands

Package `dutygraph` (0.2.1) for advisors and partner firms: `npm install -g dutygraph` (published November 12, 2026); `npm --prefix cli pack` makes the same package locally. Uses DutyGraph's MCP endpoint and the advisor's existing company access. Sign-in, company admin, Repo sync, strategy, requests, inbox, agent specs and gap briefs are implemented. Independent review findings and validation are recorded in [the review log](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/../redteam/2026-10-31-dutygraph-cli/FINDINGS.md). See [progress](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/PROGRESS.md).

Run from the repository with `dutygraph <command>`. Build the standalone entry point with `npm run build:cli`, then run `node cli/dist/main.js --help`.

Sign-in uses the browser and requests read/write access. It cannot send email. A Settings token with explicit email permission is required for sending; email commands require `--send` and confirmation or `--yes`.

[Authentication](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/AUTH.md) · [Agent specs](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/AGENT-SPECS.md) · [Decisions](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/DECISIONS.md)

## Companies and people

```sh
dutygraph companies
dutygraph use "Northstar Parts"
dutygraph roster import ./fictional-roster.csv
dutygraph roster import ./fictional-roster.csv --apply --yes
dutygraph team --team Operations
dutygraph team --json
dutygraph team --csv
dutygraph person add --name "Lee Park" --email lee@example.com --role Coordinator --team Operations
dutygraph person fix lee@example.com --role "Operations coordinator"
dutygraph person fix lee@example.com --manager-email robin@example.com --external-id staff-12
dutygraph person fix lee@example.com --left --note "Left the company"
```

`use` accepts an id or a unique name, ignoring case. Ambiguous matches are listed without changing the selection. `--company <name or id>` overrides the saved company for one command. Selection is stored separately for each origin.

Roster import previews by default. Applying it asks for confirmation unless `--yes` is supplied. Retrying the same file uses its bytes and company id for idempotency. Files must be regular UTF-8 files of at most500,000 bytes; symlinks and FIFOs are refused. Import creates people, not invitations. CSV output protects spreadsheet formula cells.

Team shows each person's latest active request. The footer counts that request's invitation and answer, not every historical request. Invited means a link was issued; its time comes from the existing issuance audit. It does not establish email delivery. Unknown times remain unknown; counts use recorded invitation and valid answer presence, independently of timestamps. Fully denied answers are excluded, matching requests and inbox. Confirmed Task Cards use current confirmation state. People who left are labelled separately.

Person changes show before and after, use the version just read and refuse conflicts. Leaving is a separate update through the existing departure route; it revokes open access without reassigning work. These commands do not send email.

## Add an existing client

```sh
dutygraph client add --name "Example Parts" --method signed_sow --reference "SOW-104" --note "Approved by the owner" --website https://example.com
```

`client add` calls the MCP tool `add_client`: the Accounts route for an existing client. The deployment's enabled activation methods, the reference rule (`signed_sow`, `enterprise_contract`, `stripe_payment`) and the firm's second-approver rule apply. `--note` says who approved the engagement. A token limited to chosen companies (Settings › MCP access › Companies, SQL 0128) cannot add a company.

## Pitch to Package (set up a prospect's call)

```sh
dutygraph pitch new --name "Example Golf Shops" --website https://example.com --contact "Sam Reed" --email sam@example.com --title "CIO" --basis referral --relationship warm_introduction --note "Introduced by a partner"
dutygraph pitch show
dutygraph pitch prepare plan.md
dutygraph pitch prepare plan.md --apply --yes
dutygraph pitch video https://example.com/video.mp4
```

Fills the Plan the call page of Pitch to Package through the page's own record, on the revision read (matt, November 10: "I give you a name, you go do research, and you do every bit of the setup"). `new` adds the company and the person (the same checks as Accounts > Add account; nothing is sent). `prepare` reads a Markdown call plan: `# Call` (`when: ...`, `person: buyer | influencer | mentor | partner`), `# What we know`, `# Before the demo` and `# After the demo` (each question is `## <label>`, the question, up to four `- ` prompts and `> ` advisor notes), and `# Video script` (up to six `- ` lines). Only the parts in the file change; a half of the questions that is given replaces that half. It previews by default, refuses a file with a mistake, and asks before saving unless `--yes`. `video` puts the rendered video's https link on the plan. `show` prints the plan. These commands cannot approve a script, start a call, save a transcript, change the package, send it or email anyone: Approve and Send stay on the page. A plan whose package was sent is not changed. The FDE skill pack has a playbook for the whole set-up (`set-up-prospect-call`).

## Client setup (before onboarding)

```sh
dutygraph setup start --sponsor "Sam Reed" --team "Customer service" --from facts.json --roster team.csv
dutygraph setup status
dutygraph setup show
dutygraph setup show casey@example.com
dutygraph setup export --dir client-setup
dutygraph setup file
dutygraph setup role casey@example.com role.md
```

Runs a new client's setup ([docs/client-setup.md](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/../client-setup.md)). `start` makes the sponsor's personal link, filled in with what is already known, and prints it once; nothing is emailed. `status` shows whether the sponsor sent it and who has not answered. `show` and `export` give each person's answers and role file, to write their questions from with `ask`. `file` puts the people into the work map and the documents into Discovery › Files again (DutyGraph does this by itself when something is sent). `role` saves a role file you rewrote; it is marked not checked.

## Onboarding (North Star session)

```sh
dutygraph onboarding status
dutygraph onboarding readout --out readout.md
dutygraph onboarding fill north-star.md
dutygraph onboarding fill north-star.md --apply --yes
dutygraph onboarding fill casey.md --person casey@example.com --apply
dutygraph onboarding transcript call.txt
dutygraph onboarding transcript call.txt --apply
dutygraph onboarding export --out onboarding.json
dutygraph onboarding import onboarding.json --apply
dutygraph onboarding persona riley@example.com --out project-manager.md
```

Reads and fills the same server record as the advisor's Onboarding page (SQL 0126); the page shows a change within 15 seconds. `status` lists each person with their manager, where they are in the cascade (session, saved, open, locked) and how many questions they answered. `readout` is one Markdown document: the session's files, then each person's. `fill` takes Markdown in the readout's own shape (`# <file name>`, then `## <what the question fills>` with the answer under it) and fills the North Star session, or with `--person <email or id>` that person's answers; only the questions given change, a part for a file with no match is reported, and a typed session answer replaces that question's transcript write-up, as on the page. `transcript` takes the call's transcript as a text file (from any note-taker): the company's AI drafts an answer to each session question with the line of the call it stands on, the preview lists the drafts and what the call did not cover, and `--apply` keeps the transcript and saves those same drafts. A question that already has an answer is kept unless `--replace` is given. With no AI connection nothing is drafted and the reply says so. `export`/`import` move the whole state as JSON for edits no other command covers; import refuses a file whose revision is stale. Fill and import preview by default and ask before saving unless `--yes`. Nothing here emails anyone, presses Save and send, or marks a section saved. A company has onboarding on the server once its Onboarding page has been opened after SQL 0126 ran.

`persona <email or id>` (MCP `get_role_persona`, November 12, 2026) writes one role, ready to talk with, as Markdown: the rules for answering as the role first, then its AI persona, its role profile and its confirmed Task Cards. Give the file to any AI (or ask Claude Code to read it) and ask the role questions. The AI speaks for the role, not the person: it opens with "AI read of the \<role> role, from its role profile. Not \<name>'s own words.", decides nothing, and turns what the profile does not say into a question to send to the person. An unapproved profile can be tried and says so. The person's own answers, drafts and suggestions are never in it.

## Export the Company Repo

```sh
dutygraph repo export ./northstar-repo
dutygraph repo export ./northstar-repo --force
```

Export downloads all pages with one fingerprint, checks every SHA-256 and writes a private `.dutygraph/manifest.json`. A changing fingerprint restarts the download once before any files are written. A second change stops it. An existing nonempty folder is refused unless `--force` is given; force replaces the exported files but preserves unrelated files.

Remote filenames cannot be absolute, traverse folders, use symlinks, collide by case or overwrite `.git` and the local manifest. A user-selected target directory may itself be an absolute path. Downloads are limited to20,000 files/200 pages,8 MiB per file and64 MiB total. Larger exports stop with a size error. Export does not make changes in DutyGraph. The export permission is the existing download permission.

The manifest stores the origin, company, Repo fingerprint, file hashes, editability and Notes versions. Generated files and identity, evidence, strategy-card, schema and runtime files are not editable through CLI push. Pull prepares editable draft regions and local Git snapshots as described below.

## Pull and send advisor drafts

```sh
dutygraph repo pull ./northstar-repo
dutygraph repo status --dir ./northstar-repo
dutygraph repo diff --dir ./northstar-repo
dutygraph repo push --dir ./northstar-repo --dry-run
dutygraph repo push --dir ./northstar-repo -m "Questions for the owner"
```

Pull adds `AGENTS.md`, `CLAUDE.md` and a local Git commit. It never configures a remote or pushes Git. Use a standalone folder; Git configuration that can run commands, external pointers and links are refused. Pull refuses unpushed changes unless `--discard` is supplied. The expanded working files, manifest and retained local files must fit the same local size bounds before any files are replaced.

Edit only the text between the advisor draft markers in editable files. The compiled content above is read-only context. Changes outside the draft region, deleted files and generated records are blocked. A save is always an advisor draft, even when the advisor also has confirmation permission. Confirmation happens in DutyGraph.

Push previews changes and asks for confirmation. `--dry-run` saves nothing and is accepted only for push; flags for another Repo action are refused. A stale Notes version stops only that file and writes a collision-safe `.theirs.md` copy for comparison; it does not overwrite the local draft. Successful files advance their local baseline. Retrying unchanged saved drafts creates no new Notes version. A metadata-only receipt records verified successes. Identical document names and bytes may reuse one stored document; each local path keeps its own baseline, and the receipt counts the unique stored document once. The local journal keeps the operation retryable if recording that receipt or making the local Git commit fails. Each push is limited to 1,000 drafts and 1,000 documents; larger changes must be split before sending.

Put new documents in `inbox-out/documents/`. Existing advisor intake types and the 4 MiB limit apply. Files travel in 1 MiB chunks and their complete hashes and types are checked before local conversion is queued. An expired upload is reported and a later retry starts a fresh session. Uploading does not run AI, accept proposals or add a document to the Company Repo. Review and publication stay in DutyGraph.

## Strategy and leaders

```sh
dutygraph strategy --json
dutygraph leaders grant lee@example.com --level department --department Operations
dutygraph leaders remove lee@example.com
```

Strategy is read only. Leader changes ask for confirmation and use the existing company permission checks. A read-only token cannot change leaders.

## Questions and returned answers

```sh
dutygraph ask lee@example.com "What starts this task?" --title "Task details"
dutygraph ask lee@example.com --file ./questions.md
dutygraph ask lee@example.com "Who receives the result?" --send
dutygraph requests --open --team Operations
dutygraph requests --times --json
dutygraph inbox
dutygraph inbox --since 2d
```

`ask` creates a draft and shows its email preview. It takes 1–10 questions of at most 200 characters each. A question file is a regular UTF-8 file up to 32 KiB, with one plain question or Markdown bullet per line. Blank lines and headings are ignored; code fences and links in the filesystem are refused. Use positional questions or a file. The default due date is seven calendar days from today in America/New_York; `--due YYYY-MM-DD` chooses another date.

Email requires `--send`, confirmation or `--yes`, and a Settings token with both `write` and `send_email`. Scope checks happen before creating a send-intended draft. The confirmed recipient address is checked again inside the send transaction. A changed address, stale version, departed person or existing send is refused. The missing-AI warning is also preserved: configure the approved AI connection or review the existing web warning flow. `--yes` does not bypass that gate. An uncertain provider result is not retried automatically. Provider acceptance does not prove inbox delivery.

Requests show the first link-issue time and first valid answer time. These are not email delivery receipts. Median response times exclude missing or invalid times and include sample counts. Past due marks unanswered open requests.

Default inbox reads arrival metadata, including accepted answers, and remembers the response IDs it showed in private `inbox.json`, separately for each origin and company. This catches late commits with older timestamps. It stores no answer text. `--since` is an explicit historical view and does not update the saved default view. The seen-ID history is bounded at 20,000 answers per company; hitting a bound refuses to advance state. Review larger histories in DutyGraph.

## Export agent specs and gap briefs

```sh
dutygraph agents list --json
dutygraph agents export <id-or-proposal-key> ./agent-spec --format agents-cli
dutygraph agents prompt <id-or-proposal-key>
dutygraph gaps list --code owner_missing --json
dutygraph gaps brief <gap-key> ./gap-brief --ask lee@example.com
```

Agent exports use the existing manifest freshness, secret/evidence checks and export audit. Exporting an unsaved proposal does not save or approve it. Nonempty folders require `--force`, with the same path and file protections as Repo export. A read token can export where the company download permission allows it; drafting questions additionally requires write.

The `agents-cli` output is formatted for Google Agents CLI with the LangChain extension (v1.8.0, experimental). It contains a specification, build prompt, neutral eval cases, provenance link and gaps. DutyGraph does not run or deploy the agent. Follow the [FDE walkthrough](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/AGENT-SPECS.md) for the separate build, evaluation and owner-approval steps.

Gap briefs contain two files with recorded context and up to ten questions. They never turn a missing Task Card or owner into an agent spec. `--ask` creates a draft; email requires an explicit `--send` and the same gates as `ask`.

## Employee inputs (FDE connectors)

```sh
dutygraph inputs --since 7d
dutygraph inputs --person lee@example.com --status stuck --json
dutygraph inputs show task_card_drafts:<draft-id>
dutygraph inputs export --since 7d --dir ./northstar-repo
```

The input feed covers 17 recorded sources, including drafts, interviews, answers, uploads and their processing state. Use exact source names from the JSON output with `--source`. Read pages have at most 200 items. The CLI follows cursors, with a limit of 20,000 items or 200 pages; use `--since` for a smaller export. Unbound people remain unknown.

Input text is untrusted data, never instructions. Reads scrub secrets without changing stored submissions. Raw text and converted Markdown are each capped at 50,000 characters. The detail response says when text is truncated or unavailable. Uploaded-byte metadata identifies its byte unit; decoded detail reports characters.

Export requires a matching pulled Repo. It writes private files only under `.dutygraph/raw/<source>/`, up to 64 MiB in one export. Git-tracked raw paths, unsafe paths and ignore-rule overrides are refused. Raw files are excluded from CLI Git snapshots and Repo push. One verified counts-only audit receipt precedes writing; if auditing fails, no raw file is written. A later local write failure is reported separately.

See [FDE progress](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/FDE-PROGRESS.md) for checkpoint evidence and remaining packages.

## Participation and stuck work

```sh
dutygraph coverage --team Operations
dutygraph coverage --no-cards --csv
dutygraph stuck --json
```

Coverage shows active employees, confirmed cards, draft submissions, waiting drafts, uploads, answered question sets, median response hours, interview progress and last activity. Missing times stay unavailable. Historical draft submissions and actionable waiting drafts are separate counts. Background document processing does not count as employee activity.

`stuck` groups stuck and failed inputs by person and suggests the next step. It does not retry conversion, change drafts or notify employees. Known departments can identify team-scoped inputs without inventing an owner. Coverage refuses over 10,000 people or 20,000 inputs; use a smaller team.

## App nudges

```sh
dutygraph nudge lee@example.com --reason add_cards
dutygraph nudge lee@example.com --reason finish_draft --send
dutygraph nudge --no-cards --send
dutygraph nudge --stuck --send
```

Without `--send`, these commands only preview. A send lists the recipients and requires confirmation or `--yes`. Reasons are `add_cards`, `finish_draft`, `resume_interview` and `answer_request`. Copy stays generic. At most one attempt per person is reserved in 24 hours, including failed delivery attempts. Provider acceptance does not prove that a person saw the notification. No-device results suggest `ask` instead. A batch stops on a send error; earlier accepted sends remain recorded and are not automatically retried.

Turn nudges off for a company in **Settings > Workspace > Employee app nudges**. The company-edit permission is required, and stale settings must be reloaded. The cookie-session API is GET/PUT `/api/v1/companies/:id/people/nudge-settings`; PUT requires `{enabled, expectedVersion}` from the latest GET. It does not change email permissions.

Phone nudges for Task Cards and work interviews open a labelled screen that continues in the employee web app. Task Card confirmation remains in that web app; the phone fallback may require sign-in.

## Help an employee finish

```sh
dutygraph inputs show task_card_drafts:INPUT_UUID
dutygraph assist task_card_drafts:INPUT_UUID --from draft.json --preview
dutygraph assist task_card_drafts:INPUT_UUID --from draft.json --send --nudge
```

Use only facts in the employee's source. The existing Task Card contract requires a title, duty, current/proposed kind and work type; if any is missing, the server returns questions and refuses to invent it. Other absent fields remain empty and appear as questions. Preview is the default; `--send` and confirmation place the draft in that employee's My work. `--nudge` additionally previews and sends a generic app reminder where available.

The employee sees who prepared it and checks it before confirming. Advisors, including sample-person preview sessions, cannot confirm prepared drafts. Earn attribution stays with the employee and follows the existing confirmation and pay rules. A changed source requires a new preview; retrying the same request does not create another draft. Binary uploads need readable text before assistance.

This requires migration [0122](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/../neon/0122-fde-prepared-drafts-plain.sql). The optional upstream Task Card notes feed is available only where that separate upstream table exists.

## Weekly activity and a CEO update

```sh
dutygraph stats --since 30d --json
dutygraph report ceo --since 30d --out ./ceo-update.md
dutygraph report ceo --out ./ceo-update.md --push --dir ./northstar-repo
```

Weeks use UTC. Activity and first owner confirmations use recorded events. Response counts and timing use the existing request validity rules; advisor-prepared drafts are excluded from employee submissions. Repo state, gaps and Strategy Card state are current snapshots. Their historical values remain null. Missing times display as “not available.”

Reports use a fixed template. Fill every reasoning slot from evidence and remove its comment before submitting. Keep the source metadata at the top: it binds the report to its company and origin. Existing analysis is never overwritten; choose another filename for a new report. Push asks for confirmation and submits only that finished document to intake as a Progress update. It does not send the report to the CEO or publish it in the Repo. Raw exports cannot be used as report paths or intake sources.

## Strategy frameworks

```sh
dutygraph frameworks
dutygraph frameworks run swot --preview
dutygraph frameworks run swot
dutygraph frameworks show swot
dutygraph frameworks review swot <boxId> --accept "Recorded evidence supports this"
```

Run uses the company's approved AI connection and asks for confirmation. Sample companies use labelled sample output. Missing inputs and connection refusals are preserved. Review uses the latest run and a recorded box ID, requires a reason and confirmation, and retains the server's freshness checks. An advisor's accepted framework box is not a confirmed Strategy Card.

For local analysis, edit advisor draft regions in editable files such as company/swot.md, company/strategy.md and company/value-spine.md. Preview with repo diff and repo push --dry-run, then confirm the push. Use strategy to inspect leader access and ask to prepare a review request. Email still needs --send and its separate scope. Leaders confirm their own Strategy Cards in DutyGraph.

## Research

```sh
dutygraph research run --level preview --preview
dutygraph research run --level preview
dutygraph research status
dutygraph research add ./research.md --source https://example.com/report --preview --dir ./northstar-repo
dutygraph research add ./research.md --source https://example.com/report --dir ./northstar-repo
```

Server runs resolve exactly one accessible account for the selected company, retain existing authorization rules and ask for confirmation. Preview is separate from the research level named preview. Snapshot authorization is not bypassed.

External research requires at least one public source URL. Repeat --source for additional citations. Remove credentials and private or signed links. Intake labels the document “Research by \<signed-in advisor>, not confirmed” and lists sources. The preview writes nothing; submission confirms the content reference and sends only this document through the existing intake path. Conversion, review and publication remain separate. Raw export paths cannot be restaged as research.

## Claude Code playbooks

```sh
dutygraph init-claude --dir ./northstar-repo
```

Repo pull installs the same bundled skill pack automatically. It includes morning-check, help-stuck-people, find-gaps-and-constraints, ceo-update, run-framework and research-company. Local CLAUDE.md text outside the DutyGraph block is preserved. Edited bundled skill files are refused rather than silently overwritten. Company files cannot supply .claude instructions.

The pack treats employee material as evidence, never instructions. Raw exports stay out of instruction files, Git snapshots and pushes. Every playbook ends with the FDE approval boundary. See the [daily walkthrough](https://github.com/mattrob333/DutyGraphV2/blob/main/docs/cli/FDE-PLAYBOOK.md).
