The commands

How the tree is shaped

Nouns carry their verbs, gh-style — vitrinka board push, vitrinka task create, vitrinka sprint complete. Only three leaf verbs sit at the top: status, doctor and update (plus help and completion); bare vitrinka on a terminal opens the dashboard. There are no aliases: an old spelling (install, open, set push) is an unknown command — exit 2, naming the nearest spelling when one is close, and vitrinka --help. Every noun, verb, flag and default is generated from the binary itself into the CLI reference; this page says what each noun is for and which verb you reach for first.

Capture and publish

Work and QA

The task engine

The PM engine is reachable from the terminal, with the same vocabulary the browser and the MCP tools use.

vitrinka task list --sort priority,-due
vitrinka task create "Discount applies twice" --type bug --priority high
vitrinka sprint complete 12 --carry next

You, search and review

Search from the terminal

vitrinka search is the ⌘K palette in a shell: one call runs every group and prints each group's ranked hits. A number (№432 or #432) pins that annotation thread or task; any fragment of three or more characters matches, mid-word included. Task and page rows carry their canonical URL — paste it as printed. --resolve reads the text as ONE task reference — title words, any id spelling, a URL, a branch, bugs under <epic>, mine — and answers a verdict with at most five candidates instead of every group. task search is the ranked search over everything a task carries — title, body, fields, refs and comments, a typo searching its correction too — in this checkout's project unless --all; --type, --state, --parent and --epic (any depth) narrow it, a value naming nothing fails with the allowed ones, and --within <task> searches one task's own tree.

vitrinka search "checkout crash"
vitrinka search onboarding --groups tasks,pages --project shop
vitrinka search "bugs under checkout" --resolve
vitrinka task search coupon --epic 461 --type bug
vitrinka search query "select name, count(*) n from agent_calls group by name order by n desc"
vitrinka search resolve https://app.vitrinka.ai/w/acme/p/shop/t/461
vitrinka fav add task 461 --folder Releases

search query is the read side of the agent-calls ledger — every agent-driven call lands in agent_calls as one row — beside the board and task facts (ai_usage, boards, board_cards, sets, project_settings, tasks, task_events, task_labels, workspace_events, review_rules, project_deploys, and sqlite_master for the schema). It runs ONE read-only SELECT, for the workspace owner only, capped at 1000 rows and 5 seconds, and every call is audited; --param binds each ? in turn. search resolve answers what a vitrinka link points at — kind, workspace, title, canonical URL — in any workspace you belong to; a link you cannot see is one "not found", whatever the reason. The MCP twins are search, query and resolve_url.

Machine, repo and session

Setup and administration

Ask in plain words

docs ask translates a plain-language request into one vitrinka command through a local claude -p call, shows it to you, and runs it only after you agree.

vitrinka docs ask "show me open work on this branch"

Scripts and agents

Every command takes --base, --json (one envelope on stdout — v, ok, verb, data, diagnostics, next, exit_code; --json=id,title keeps only those fields of data), --jq '<expr>', --no-input (never prompt; also VITRINKA_NO_INPUT=1 or CI) and --yes (accept the proposed plan). Exit codes: 0 ok · 1 failed · 2 misuse · 3 nothing found (work watch --once) · 4 sign in first · 5 a step needs a human — the plan is in data, and next[].cmd is the rerun with --yes · 130 cancelled — help guides.

Offline: the outbox

A write the deployment cannot receive is not lost. When the network is down, or an agent's MCP connection has dropped and the network went with it, these commands queue their request on this machine instead of failing: task comment, task update, task create, task label, task upload, task handback (without --transcript), me todo add (without a milestone or dependencies), me todo done and board compose <board> --file -. board compose takes the same arguments as the compose_board MCP tool.

A queued write exits 0 and prints ⧗ queued offline. Under --json, data.queued names the entry and a queued diagnostic lets a script branch on it. The queue lives beside the CLI config in ~/.config/vitrinka/outbox/ ($XDG_CONFIG_HOME/vitrinka/outbox/ when set) and keeps the workspace each write was made in.

Before its first request, the next command that reaches the deployment replays the queue, oldest first. The SessionStart hook replays it too and reports the result. Every write carries an idempotency key from its first attempt, so it lands exactly once, even when the first attempt reached the server but its answer was lost.

vitrinka outbox list              # pending, parked (with the server's reason), recently replayed
vitrinka outbox flush             # replay now
vitrinka outbox retry <id>        # put a parked write back in the queue
vitrinka outbox drop <id>         # give one up for good

The server parks a write it refuses, such as one aimed at a deleted task. A parked write stays put until you retry or drop it. An expired sign-in parks nothing: the queue waits for vitrinka auth login. Pass --no-queue, or set VITRINKA_NO_QUEUE=1, to make CI and scripts fail instead of queueing.

Publishing without the CLI

Nothing about publishing requires the CLI. From any job you already run, mint a set key and stream a tarball into it — no SDK to install, nothing to keep up to date in the pipeline.

tar czf - -C ./shots . | curl -sS -X PUT --data-binary @- \
  -H "Authorization: Bearer $VITRINKA_TOKEN" \
  "$VITRINKA_URL/api/v1/sets/myapp/main/nightly/content?kind=screenshots"