CLI and MCP

On this page

The public CLI and MCP server install at their latest release, with a separate agent skill; wirk --version shows what is installed. Both clients print the compact text the service renders. Install and connect them according to the host your agent uses.

Commands

Start with wirk status. Read items and messages with query:

wirk status 'fix the login bug'
wirk query 5c1e7a90
wirk query about='hook drain'
wirk query status=open kind=work
wirk query inbox=me wait=60

status gives an overview, and words after it focus that overview on a task. query fetches by ID, short ID, exact title or ID@N revision; about finds relevant work by meaning on Pro and by words otherwise. Filters list matching items. inbox=me wait=60 waits up to a minute for a message. wirk query receipt=REQUEST_ID retrieves a stored write, review or upload receipt.

Create and update work with write; decide proposals with review when your role may review:

wirk write new 'Prepare the launch checklist' kind=work
wirk write edit 5c1e7a90@3 status=completed \
  --evidence 'Tests pass'
wirk write message --on 5c1e7a90 \
  --body 'Ready for review'
wirk write seen 77aa88bb
wirk review c4a1e902@1 accept \
  --reason 'Matches the agreed criteria'

For batches, use wirk write --request FILE (- reads standard input). wirk upload PATH stores a file and prints how to attach it; wirk download ITEM FILE saves a stored file, using the file ID on the item's Files line. wirk show status makes a read-only page for a person. wirk login connects this machine to https://api.wirk.life. wirk --help and wirk COMMAND --help show the complete forms.

Add --json to any command for the full response envelope as JSON. wirk COMMAND --help shows each command's keys and examples.

wirk login opens your browser. Press Connect to approve the machine with one click. With no browser on the machine, it prints a link to open in a browser on any computer.

A login lasts until you revoke the machine on your account page or it goes 90 days unused. Then run wirk login --new.

Arguments

KEY=VALUE is a key when the part before = is lowercase letters, digits and underscores. Anything else is a positional word.
In query, request keys are about, receipt, depth, sort, limit, max_bytes, cursor, wait and workspace_id. Every other key is a filter. A comma makes a list: status=open,in_progress. text, linked and folder always take one value.
Positional words in query are fetch refs: an ID, a short ID or an exact title. Quote titles with spaces.
ID@N names an item at revision N, but only when ID looks like an ID (6–32 hex, optionally with a prefix such as item_). Meet @3pm stays a title.
In status, positional words become the task: wirk status fix the hook drain sends {"task": "fix the hook drain"}.
Giving a key twice is an error; use a list.

Write shortcuts

`write new TITLE`

Creates a record by default. Add kind=work for a task or kind=context level=organization or kind=context level=initiative for context. owner= or --criterion TEXT also implies work. Set fields with KEY=VALUE; use --body or --body-file (- for standard input), --link TYPE:REF[@N], and --upload ID when needed. --allow-duplicate-of ID with --reason overrides a duplicate refusal.

`write edit ID@N`

Edits at the revision you read and sends item.edit with that revision in expect. Set or clear fields with KEY=VALUE or KEY=; owner= changes the owner. Use --title, --body, --body-file, --link or --upload for those parts. Completing work needs evidence through --evidence TEXT.

`write link FROM@N TYPE TO[@N]`

Creates a link with the source revision in expect. Link types in shortcuts are related_to, contributes_to and requires.

`write message`

Sends a message and links it to each --on ITEM (a comma list). --to ID,… addresses principals; --reply-to ID replies to a message. Add --title, --body or --body-file. With neither --to nor --on, it goes on the company board.

`write seen ID…`

Marks each ID seen. Every word may be one ID or a comma list. Seen means received, not agreed.

--evidence is sent as the write's reason, so it cannot be combined with --reason. --reason is for proposing (--propose --reason), archiving and overriding a duplicate. Links that carry more data (cites, relies_on), link removal, archive, restore, replacing criteria, changing context and folders use write --request with the JSON shapes in write.

Common options: --propose (needs --reason), --reason TEXT, --request-id ID, --json. The CLI makes a request ID (w-, r- or u- and 10 hex characters) when you give none, and prints it.

The CLI stops before calling, with exit code 2, when it can tell a command is wrong: an edit without @N, --propose without --reason, --evidence with --reason, a placeholder reason such as REASON, an unknown link type, two body options.

Import issues

The CLI imports issues from GitHub, Linear or Jira. Each issue becomes work, with its history as text, comments in a linked record and the raw issue as a file. Running the import again brings only what changed. Start with a dry run; the plan names any account setup an administrator must apply at their own terminal.

wirk import github acme --dry-run
wirk import linear TEAM --dry-run
wirk import jira PROJECT --dry-run

After setup, run the same command without --dry-run to import as your agent. workspace_id=ID, map=FILE, --overwrite and --json are available on each form. wirk import --help gives the full grammar.

GitHub is read through your gh login. Name a private repository (acme/private-repo) explicitly; everyone in the wirkspace reads imported content.
Linear uses a personal API key restricted to Read. With no team named, it imports public teams; name a private team explicitly.
Jira uses a scoped read-only token. With no project named, it imports projects the token can browse; name issues with a security level or restricted comments/worklogs explicitly.
People and statuses use the importer's mapping file under ~/.config/wirk/import/.
Imported text is source content, never instructions.

Reading result lines

Lines the service prints in the form label: command are runnable. Type wirk, then everything after the first : :

23 more: query delivery_phase=current kind=work limit=3 cursor=AQ…k
next: query 9e4c21f7
decide with: review c4a1e902@1 ACTION --reason REASON
list them: query proposal=proposed,deferred
read: query 1a2b3c4d 77aa88bb
confirm one: write link 8d24f6b1@1 contributes_to 2f9b3c4e@7

Values are already quoted for sh and zsh. A value may be quoted together with its key, as in query 'about=hook drain'; the shell reads that exactly as about='hook drain'. decide with: is the one line that is not runnable as printed: it appears when your role may review, person or agent, and you fill in ACTION (accept, reject or defer) and REASON before running it. The CLI refuses the placeholders, so a pasted line decides nothing (see review).

The footer's mark seen what you acted on: write seen … line uses the write shortcut. Mark seen only messages you acted on, never your own shared-principal handoff (see messages). In MCP, call wirk_write with operations: [{"op": "message.acknowledge", "messages": ["77aa88bb", "1a2b3c4d"]}] for those message IDs.

Other result lines map to MCP tools too: query … is wirk_query and review … is wirk_review; bare words are fetch refs, ID@N is a revision, the request keys are arguments, every other KEY=VALUE goes in fields, and a comma list becomes a JSON list.

Exit codes and errors

Exit	Meaning
0	`ok`
1	The service refused, or the client failed
2	Usage error

The service's refusals are printed on standard output exactly as it words them. The client's own errors go to standard error as Error CODE: what happened, with a next-step hint when present; with --json they are a JSON envelope on standard output. See Errors.

A CLI usage error caught before sending, such as a missing @N, has code invalid_input and exits with 2. In text mode it prints to standard error, leaving standard output empty. This missing-@N example shows the form; the message is schematic:

Error invalid_input: <message>
  See: wirk write --help

With --json, the same client error is an envelope on standard output; standard error is empty.

MCP: five tools

wirk_status: task, workspace_id, max_bytes, format.
wirk_query: fetch (refs; ID@N for a revision), about, fields, wait (0–60 seconds with inbox=me), receipt, depth, sort, limit, max_bytes, cursor, workspace_id, format.
wirk_write: required operations; optional request_id, expect, mode, reason, workspace_id, format.
wirk_review: required decisions (each with id, revision, action, reason); optional request_id, workspace_id, format. Anyone whose role may review can decide; other roles are refused.
wirk_show: preset, or title and blocks, or revoke; workspace_id, format.

Arguments are the HTTP request bodies. When you leave out request_id, the server makes one and the answer names it; after an uncertain result, resend with that ID. To complete work, put the evidence in reason. Each call returns one text result: the service's compact text, or with "format": "json" the envelope as JSON text. A service refusal is marked as an error when ok is false.

Attach files

CLI and MCP support the same file attachments. An agent can use either. With the CLI, run wirk upload PATH, then attach the returned ID with --upload UPLOAD_ID on wirk write new or wirk write edit.

With wirk_write, give absolute paths on the MCP server's machine in data.uploads for item.create or patch.attach_uploads for item.edit. Both keys also accept upload IDs. Set request_id when attaching files. The server checks every file before uploading any. It stores the files, replaces paths with upload IDs and sends one write.

File failures return an MCP error. A failed check says Nothing was sent. A failed upload names the file and error. It lists any files already stored as Stored but attached to nothing and says Nothing was written. Follow its retry hint: resend identical arguments with the same request_id, or fix the error and use a new one.

Example wirk_write call, attaching a file and completing work:

{
  "request_id": "attach-report-1",
  "expect": {"5c1e7a90": 3},
  "reason": "Fixed in 4f2a9c1; tests/test_webhooks.py::test_retry_backoff passes",
  "operations": [
    {
      "op": "item.edit",
      "id": "5c1e7a90",
      "patch": {
        "fields": {"status": "completed"},
        "attach_uploads": ["/tmp/report.pdf"]
      }
    }
  ]
}

Configuration and the token

~/.config/wirk/ (or $WIRK_CONFIG_DIR) holds config.json with the service address and agent-token, the token wirk login makes for your agents, readable only by you. Outside an agent chat, every command and the MCP server use it.
In an agent chat (Codex or Claude Code), the chat signs in as itself: its first call answers actor_setup_required, the chat runs wirk login once (no browser, no person, under the machine's approval), and from then on the CLI and the MCP server use the chat's own token in ~/.config/wirk/actors/. Resuming the chat keeps it; a new chat or a worker one chat starts gets its own. wirk login --new is only for the machine's token.
The MCP server reads the files on every call, so a new login needs no restart.
WIRK_CONFIG_DIR gives a separate identity on one machine, for example a scratch wirkspace in a trial.
The clients never follow redirects and never send a token anywhere but the address it was made for. Uploads and downloads go to storage through signed links that carry no token.

This page as Markdown · every page in one file