chief — command reference

Bounded output, stable ids that are valid arguments to the next command, structured errors, and no interactive prompts under any condition. Every command takes --json for machine-shaped output and --verbose for diagnostics on stderr.

Exit codes: 0 success, 1 the request was wrong, 3 transient — retrying may help.

search — investigate indexed original artifacts

chief search "telnyx contract terms"
chief search "renewal" --strategy lexical --source gmail --since 30d
chief search "project handoff" --participant person@example.com --limit 15

Start source investigation here. Original artifacts remain searchable without extracted claims, prior who resolution, or interpreted-memory acquisition. Hybrid is the default and searches the exact supplied query. --strategy lexical requires no query embedding or expansion; semantic searches by meaning. --query-expansion expanded explicitly adds model-generated variants for semantic or hybrid retrieval. It is invalid with lexical retrieval.

Default output is the service-rendered source evidence view. --json returns the same chief-artifact-evidence-v1 packet: passages reference sources and excerpts, retaining exact version/manifest/chunk reads and Unicode ranges. Acquisition receipts distinguish searched, unavailable and unrequested arms. Inspect excerpt selection and coverage; a lexical source_prefix excerpt may require a wider source read to expose a stemming match. Source-time scope applies to the source manifest, not each message inside a conversation window. Notes require explicit created/created_at provenance matching the manifest timestamp; filename, filesystem and observation-date fallbacks cannot satisfy time scopes. Granola participant filters use explicit frontmatter declarations, not inferred title names. Unproven legacy metadata remains available to read and sources remain discoverable without those filters.

recall — optional interpreted memory and source passages

chief recall "telnyx contract terms"
chief recall "renewal" --since 30d --source gmail --limit 5
chief recall --shape unresolved_thread

Every page states which subjects its claims are bound to, and how many carry no binding at all. Read that before trusting a name in the prose: a bare first name may be several people, and one of them may not be a person.

Ordinary queries search the original question and model-generated variants together through the same acquisition service as the agent's search_memory tool. Blank-query shape enumeration preserves Core's ordering without expansion.

For a controlled operator comparison, CHIEF_MEMORY_QUERY_EXPANSION=original_only or expanded selects the acquisition policy for that recall invocation. It maps to the authenticated service request's query_expansion field; it neither changes the query locally nor chooses another retriever. Unset keeps the service default. Invalid values fail before acquisition. The receipt distinguishes a requested original-only search from provider failure. Do not persist a comparison setting in the user's shell or application config.

Default output is a readable evidence view generated by the same service as MCP recall and the registered search_memory tool. It retains full claim text, verbatim excerpts, source attribution, chronology, exact read coordinates and coverage. Detailed ranking scores and execution settings remain available in --json, which returns the complete chief-memory-evidence-v1 packet from that same acquisition. The CLI does not maintain a second renderer or retriever.

In JSON, claims remain in results; each passages entry references sources and excerpts dictionaries. Resolve those references for provenance, version-pinned read coordinates, verbatim text and Unicode ranges. Repeated records are factored within the packet; no claim ID is invented for a passage. artifacts contains current artifact metadata for claim attribution, distinct from the historical passage sources. acquisition.variants reports each query's claim and passage arm as searched, unavailable or not_applicable. Expansion failure and incomplete hydration are explicit. Claim-specific entity, shape and history constraints cannot be assumed to apply to passages; follow the receipt's widening guidance.

who — resolve a name

chief who "Max"

Returns an entity id such as e/c5m4gqagnzcr, plus who they are and the shape of your history with them. Pass that id to recall --entity when the question is about one person. Scoping usually surfaces more relevant claims, not fewer, because the unscoped page is diluted by same-name strangers.

show — claim evidence or an exact original source

chief show c/3kf9q2wmxb7n
chief show c/3kf9q2 --artifact --chars 8000

--artifact prints the source document the claim came from rather than the claim. Ids accept a short prefix.

A source dictionary entry supplies the fields for an exact read:

chief show a/<artifact-id> --version <version-uuid> --manifest-revision <revision> --manifest-hash <hash> --chunk <chunk-uuid> --adjacent-chunks 0 --start-char <excerpt-start> --chars <page-size>

The chunk selector reads the exact chunk and adjacent manifest context. Omit it to page through the whole exact manifest. --chars sets the page size and --start-char continues at the Unicode character offset in next_read; these are not embedding-unit offsets. Copy all version and manifest coordinates on continuations. Later document edits do not replace the source being read.

Drive source handles (chief show drive:<file-id>) fetch current provider text. Artifact and version coordinates read stored evidence. Source pages and exact continuations disclose their version’s acquisition coverage; a first-sheet CSV export never claims to cover other workbook tabs.

remember — record a conclusion

chief remember "Telnyx renewal moved to Oct 15"
chief remember "It's golfer's elbow, not tennis elbow" --from-user --supersedes c/k3m7x2
chief remember "..." --dry-run

Without --from-user the observation is attributed to you-the-agent, which is the safe default: an agent conclusion mislabelled as the user's corrupts the record, while a user statement mislabelled as the agent's is merely weaker.

--supersedes creates the text as a replacement claim, links it to the target, and retires the target in one transaction. Use it when you know this corrects something — you watched the correction happen. It requires --from-user.

source search — providers and indexed source aliases

chief source search gmail "waiting on my reply" --limit 5
chief source search calendar --since 0d --until +7d

Queries the source-specific reader. Gmail, Drive, and Calendar query their providers. Obsidian and Granola require a query and use the same artifact search as chief search --source obsidian|granola: hybrid retrieval of the exact query, with source-created-time [start,end) bounds. These aliases now return chief-artifact-evidence-v1 directly, replacing the earlier memory packet and claim-time filtering. Consume its source/excerpt dictionaries; use explicit recall for claim shapes, entity subjects, and interpreted history. Claim-only scopes are rejected by indexed-alias MCP/API requests.

Messages searches acquired conversation windows; device synchronization freshness is unknown. Its --since and --until bounds apply to the window's occurred_at, and at most 20 windows are returned. Read individual message sender, recipient, and timestamps before inferring a personal request.

+Nd counts forward; a bare Nd counts backward. Coverage retains the applied window. A full result window may have more matches; an empty synchronized Messages result does not establish that no messages exist on the device.

Calendars are enumerated, not searched: the query is keyword-matched against item text, so "meetings this week" matches nothing and is not evidence the week is empty. Omit the query and pass a window.

source browse — navigate indexed source identities

chief source browse "weekly planning"
chief source browse --source obsidian --path-prefix Projects/ --kind folder
chief source browse --source google_doc --limit 50 --cursor <next_cursor>

Browses indexed titles, paths and opaque source handles without content search, embeddings or provider calls. Use it when you know which document you want and need its exact artifact id for chief show, or to see what a vault folder holds. The query is a literal, case-insensitive substring of the title, path or handle; omit it to enumerate.

Folder entries derive from indexed Obsidian paths, not the live filesystem: absence does not prove a note is missing or a vault disconnected, and a new root still needs Chief's own folder picker and source grant. --json returns the chief-source-navigation-v1 packet. The MCP tool is navigate_sources.

mail — draft, edit, reply, file, label, unsubscribe, send

chief mail draft --to jane@example.com --subject "Q3 planning" --body "..."
chief mail edit 8c5bed33-431f-4c9e-8b71-fdd85bcf6815 --body "The complete revised body"
chief mail reply 1a0355903300f789 --body "..."
chief mail archive 1a0355903300f789 --dry-run
chief mail unarchive 1a0355903300f789
chief mail label 1a0355903300f789 --add Newsletters/Read --remove INBOX
chief mail read 1a0355903300f789
chief mail unsubscribe 1a0355903300f789 --dry-run
chief mail send --reply-to 1a0355903300f789 --body "..."

Triage has dispositions between archive and leave. label adds and removes Gmail labels on one message, not the thread — file a read newsletter, star a thread to return to, or drop INBOX from a single message without touching the rest of the conversation. Repeat --add/--remove for several labels. System labels are INBOX, STARRED, IMPORTANT, UNREAD; user labels use their display name.

read marks one message read. That is the provider-side way to stop a repeating run from re-reporting a thread it already handled, instead of tracking it in a local cache that drifts from Gmail.

unsubscribe asks a bulk sender to stop, using the List-Unsubscribe headers that sender published. When the sender supports RFC 8058 one-click, Chief sends the POST and reports the sender's actual answer; when it does not, nothing is sent and the published targets are printed so a person can finish by hand. Use --dry-run to see exactly which host would be contacted before anything leaves the machine.

It cannot be undone from Chief. Re-subscribing is a manual act on the sender's own site, and some senders apply one unsubscribe to every list they run. Leave mail the user needs but never opens — security and 2FA notices, fraud and account alerts, payment, delivery, legal or tax mail. A List-Unsubscribe header on that kind of message is a compliance artifact, not an invitation.

archive and unarchive are exact inverses and both act on the whole thread. undo_action only reaches effects recorded in the current session, so unarchive is how a later run corrects an earlier one. Neither label nor read has a one-tap undo; both print the exact command that reverses them.

A reply is a different verb, not a Re: subject — draft always opens a new thread. Message ids come from chief source search gmail; read the full message with chief show first, because search returns a snippet rather than the body.

draft and reply return a stable Chief draft_id. Pass that id—not Gmail's provider id—to edit. Editing replaces the complete body of the same Gmail draft in place; omit --subject to keep the current subject. It never creates a second draft and never sends.

Mail bodies are literal command arguments. When invoking Chief through a shell, protect multiline content and values such as $499 from shell expansion. Do not interpolate a JSON-stringified body into a double-quoted command. For example, a single-quoted multiline argument preserves both line breaks and the dollar sign:

chief mail reply 1a0355903300f789 --body 'Hi Jane,

Please proceed at $499.'

Chief rejects the common corrupted shape—repeated visible \n sequences with no real line breaks—before creating, editing, or sending Gmail content.

--to takes an address or a name to resolve. --dry-run shows the resolved effect and writes nothing. send delivers immediately and cannot be undone.

claim bind — repair a subject binding

chief claim bind c/3kf9q2wmxb7n --subject e/h7p4n2x6m9qd

Replaces a claim's recorded subject bindings. --subject is repeatable.

status — what is reachable, and what is covered

chief status

Reports both services, the account this machine holds, the identity behind it, coverage per source, and local understanding. Read it when a recall comes back empty: a zero result over an uncovered window means something different from a zero result over a covered one.

Desktop diagnostics show up to 20 recent active registrations and 20 connector records: installed versions, last-seen timestamps, structured-turn capability, last sync, and Messages' source cursor versus its last observed head. An active registration is not proof the device is currently online. Queued commands and expired leases are reported separately from active execution; a successful local turn is the proof that understanding has worked.

chief status --json includes checks_passed and per-source coverage_errors. Both output formats exit 1 when a required service or signed-in diagnostic cannot be checked. A successful diagnostic can still report waiting work or an offline desktop: inspect local_intelligence.state and execution_proven before calling a beta setup ready. With no credential, reachable services exit 0 and point to chief login. See the beta setup check.

Coverage is printed three ways. Core's summary carries two maps — coverage, the sources with a completed window, and coverage_errors, the sources whose ledger could not be read (UNKNOWN). A source in neither is derived by the CLI as no_completed_window (NO COMPLETED WINDOW in prose): the ledger answered and has no completed window for it, which is what a never-connected source looks like and also what a connected source looks like while its first window is still in progress. The summary cannot tell those apart, so the value names only what is established. --json carries all three as coverage_status.

Session renewal has one more typed answer. When Core is down behind the auth route, the server answers 503 with Retry-After, and every verb fails [core_unavailable] ("Chief is unavailable; retry in N s", exit 3) with the stored credential untouched. Only a 401 means the session is dead and chief login is the fix.

invite — the door, and whether it opened

Chief is invitation-only: signing in with Google creates no account without an offer. Owner only.

chief invite max@example.com --name Max
chief invite max@example.com --expires-in-hours 72
chief invite max@example.com --json

It reports whether the invitation was delivered, not whether the request succeeded. Those differ: the server creates the offer, sends the mail, and on a send failure releases the offer and answers HTTP 200 with sent: 0. Anything reading the status code concludes someone was invited when nobody was.

invited    max@example.com
           the invitation is on its way; the link expires and can be used once

NOT SENT   max@example.com
cause      max@example.com: Gmail compose is not authorized yet: ...

Exit is non-zero when nothing was sent. Invitations send through the owner's own Gmail grant, so a lapsed Google connection stops all admission — which is why the failure is the headline here rather than a detail under a success.

Running it again on an address that is still holding an unclaimed invitation replaces it. The offer token is stored only as a hash, so a mail that never arrived cannot be sent a second time; a fresh one is issued and the earlier link stops working.

re-invited max@example.com
           a new invitation is on its way, and the earlier link is now dead —
           if they still have the first mail, tell them to open the newest one

email already has access is reserved for an address that really does own a Chief account.

login / logout / mcp / config

See install.md for login and logout, and mcp.md for serving this memory to an agent.

chief config --core-url ... --integrations-url ... --refresh-self

config points this machine at a Chief. Credentials come from chief login, never from here.

Indexed Obsidian/Granola aliases use chief search and its source-time scopes, original-artifact evidence packet and exact reads. See the source-search contract above; use chief recall explicitly for interpreted memory.

intelligence — is any machine understanding your sources?

chief intelligence

Understanding runs in a harness on your own machine, so Chief can be fetching and indexing everything while nothing turns any of it into memory. This reports the state, the machines Chief has heard from and when each last claimed work, the harness queue — waiting, active, succeeded, dead-lettered — recent turns, and the exact switch to flip, named for the machine that needs it: on adil-m3: open Chief → Settings → General → Local intelligence on a Mac, on max-box: run \chief-desktop intelligence setup`` on Linux. The machine is the registered desktop that most recently claimed work, then the most recently seen.

The server reports waiting_for_device whenever work waits and no capable machine has claimed in thirty minutes, whether or not the path ever worked. The CLI reads the proof: with a past success it says your Mac adil-m3 last ran a turn 3 h ago and names the wake remedy (on adil-m3: open Chief to resume); only an account with no successful turn is told the setup switch. chief status and chief recall use the same table, so the three never disagree. --json adds what the CLI derived: remedy, remedy_device, remedy_platform, sentence, proven.

chief recall adds one line of the same when it finds no claims and no machine can be understanding: a zero over sources nothing has read is not a zero.

undo — reverse a recorded action

chief undo 8c5bed33-431f-4c9e-8b71-fdd85bcf6815

Every write Chief performs opens a row in an append-only ledger before it acts. mail archive, unarchive, label, read and unsubscribe print that row's decision: id, and undo: chief undo <id> when a shipped inverse exists — the archive today. The reversal is proven by the ledger row it appends, never by a sentence: that row is written strictly, so a Core failure can never leave a reversed answer with nothing on the ledger. An action with no shipped inverse fails typed as [not_reversible] naming the operation; the plain inverse verb is printed beside every write for exactly that case. A held write whose window is still open is cancelled before it commits instead of reversed after.

[reversal_unrecorded] is the one failure that is not retryable and not nothing: the inverse ran, and the row that proves it could not be written. Do not run undo again for that decision — the ledger still shows the action as standing, so a second call would run the inverse again; check the target by hand. The decision id a write prints comes from the tool's own receipt, never from a search of recent ledger rows, so two labels on one message each carry their own id.

runs — local-agent runs

chief runs list
chief runs show <run id>
chief runs approve <run id>
chief runs cancel <run id> --reason "wrong branch"
chief runs review <run id> --accept --note "landed"
chief runs respond <run id> --approve --remember
chief runs respond <run id> --request-key <key> --deny

A run is a harness — Claude Code, Codex — working on your own machine at Chief's direction. list and show read; the rest are the three decisions only the owner makes: let a run start, stop it, and answer an authority request it raises mid-run. respond resolves the request key when the run has exactly one pending request and refuses, listing them, when it has several. --remember turns one approval into a standing grant for that tool on that device; it is never the default. review records your verdict on a finished run's output, --accept or --discard. An answer given here is recorded on the run as responded_via: chief_cli (the desktop's own session records as the device, a browser as chief_web), so a later reader knows how the owner answered.

Refusals are typed. [invalid_state]: the run is not in a state that takes the action (not awaiting approval, already terminal, or not this account's) — chief runs show <run id> says which. [not_found]: no such run — chief runs list. [ambiguous]: several requests are pending and none was named. [bad_argument]: a verdict or decision the server does not accept. [core_unavailable] (retryable, exit 3): Chief could not reach its store and the run is untouched. The run id is sent as one percent-encoded path segment, so no character in it can change the route.

doc — create, inspect and edit documents

chief doc create --title "Q3 plan" --body "# Q3 plan ..."
chief doc create --title "Standup" --body "..." --provider obsidian --folder Daily
chief doc show a/3kf9q2wmxb7n
chief doc edit a/3kf9q2wmxb7n --expected-version google_revision_id=ALm37 --append "## Next"
chief doc edit a/3kf9q2wmxb7n --expected-version content_hash=9f1c… --body "the whole document"

create writes a Google Doc by default or an Obsidian note applied on your desktop, which comes back pending with a command id when that desktop is offline. show is where an edit's version comes from: it prints the current kind=value, whether the document is editable and why not, and the heading outline. edit names that version. If the document changed since, nothing is written: the command prints the current version and content, fails [version_conflict], and with --json returns them as current_version and current_content_markdown — merge against that and retry with the new version. --body replaces the whole document; --append inserts at the end. Never create a second document to revise the first.