Appearance
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. See progress.
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 · Agent specs · Decisions
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.comclient 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.mp4Fills 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.mdRuns a new client's setup (docs/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.mdReads 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 --forceExport 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.comStrategy 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 2dask 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.comAgent 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 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-repoThe 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 for checkpoint evidence and remaining packages.
Participation and stuck work
sh
dutygraph coverage --team Operations
dutygraph coverage --no-cards --csv
dutygraph stuck --jsonCoverage 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 --sendWithout --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 --nudgeUse 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. 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-repoWeeks 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-repoServer 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-repoRepo 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.
Source: docs/cli/README.md in the DutyGraph repository.