ASNT-118: qrate CLI: one public command for scripts and agents #153

Overview

Ship the qrate command beside the desktop app. It is the one public surface for scripts and agents: it opens projects, reports whether qrate is running and which project is open, and lets an agent read the open project. It replaces the loopback agent bridge, which is removed.

Scope

• In scope: qrate [PROJECT], open, app status|path|launch, project info, agent …, completion, man, version, help; packaging on every platform; the embedded Pi calling the CLI; user docs and the qrate-cli skill.
• Out of scope: an MCP server, offline commands against a saved .qrate file (--use), any command that writes a cell, qrate app quit.

Task Details

1. One private endpoint. app_control serves status, project info and agent calls on loopback behind a per-launch token. Only a CLI from the same release talks to it.
2. Public contract. The CLI's JSON and exit codes: 0 answered, 1 refused or failed (a refusal is JSON on stdout), 2 usage, 3 qrate unreachable. app status and project info take --format human|json, human on a terminal and JSON in a pipe.
3. Agent commands. qrate agent overview|query|program-save|program-run|thumbnails|stage-findings forward the ai::agent contract. Parameters are a JSON object on stdin.
4. Help from the parser. qrate help, qrate completion <shell> and qrate man <dir> are generated; nothing is hand-written.
5. Packaging. Windows bin\qrate.exe on PATH through NSIS and MSI; macOS Contents/MacOS/qrate-cli; Linux bin/qrate and share/man/man1; the Store MSIX carries qrate-cli.exe for its on-demand agent component.
6. Embedded Pi. agent-runtime starts Pi with QRATE_CLI and QRATE_AGENT=pi; qrate-pi-extension 0.3.0 is pinned in scripts/fetch-agent-runtime.*.
7. Docs. docs/cli/, skills/qrate-cli, docs/agent-panel.md, AGENTS.md.

Definition of Done

• No loopback server other than app_control exists in the app
• The embedded Pi and an external agent reach the same live data through qrate agent
• qrate help, completions and man pages cover every command
• ./scripts/ci.sh passes
• A pre-release run of the release workflow builds every package with the CLI inside

Estimate

In review (PR #122).

Type

Feature

Notion: https://www.notion.so/3ed21d32b13b81f0b4bcf8c0dd955d56