Quire CLI

The local quire command for Quire authentication and investigations.

Development

• Install dependencies:

vp install

• Run the unit tests:

vp test

• Build the library:

vp pack

• Run the built CLI after building:

node dist/quire.mjs --help

Project runbook

Project-specific target guidance lives in .quire/runbook.md. The runbook is a committed Markdown file for deployments, local URLs, mobile app IDs, verification commands, safety rules, setup scripts, test accounts, and runner requirements. Quire does not pre-classify every run as web, mobile, or code before the agent starts; it gives the agent the runbook path, caller context, runtime capabilities, and request so the agent can resolve the target or report the smallest missing context.

Create or refresh the runbook with:

quire setup

A typical runbook includes sections like:

# Quire runbook

## How to choose a target

If the user says prod, use the production deployment in read-only mode.
If the user asks for local verification, use the provided URL or `$QUIRE_WEB_URL`.
Do not guess ports or app IDs.

## Deployments

### dev

URL: https://dev.example.com
Safe for test accounts.

## Verification procedures

Run `vp check` for static checks and `vp test` for unit tests.

The removed quire env command now prints a migration message that points to .quire/runbook.md.

Doctor

quire doctor diagnoses the current setup before you start an investigation. It checks identity (auth + model broker), workspace runbook state, and run state (runs root writable, no stuck runs):

quire doctor                # human-readable report, grouped by section
quire doctor --json         # structured report for agents/CI
quire doctor --strict       # exit non-zero on warnings as well as failures

Each check has a stable id (e.g. auth.present, auth.valid, runbook.present, runbook.readable, runs.rootWritable) so coding agents can act on specific failures without parsing prose. Failing checks include a fix.command you can run to resolve them. Exit code is 0 when all checks pass (or only warnings in non-strict mode) and 1 otherwise.

Runs

The primary interface is text-in work. For humans, quire "..." starts a run and attaches to the live run log:

quire "Reproduce the checkout crash"
quire "Verify the login page loads"
quire run "Reproduce the checkout crash"

Use --detach to start the run in the background and print run-control commands without attaching:

quire run "Reproduce the checkout crash" --detach

Coding agents and scripts should use --json. JSON mode returns a durable run handle immediately, never prompts, and keeps stdout machine-readable:

quire run "Reproduce the checkout crash" --json
cat issue.md | quire run --json
quire status <run-id> --json
quire watch <run-id>

Continue a previous session when the first run needs more context or a retry:

quire continue <run-id> "Use the seeded buyer account and retry checkout"
printf 'Fixture account: [email protected]\n' | quire continue <run-id> --json

continue starts a new linked run, forks the prior harness-native session when available, and injects the previous transcript, handoff, evidence summary, and new caller context. The original run remains immutable.

run carries a deliberately small flag surface. Target context belongs in the prompt, --url, $QUIRE_WEB_URL, and .quire/runbook.md. Piped stdin is read automatically when stdin is a pipe or redirected file. If a positional prompt is also present, the prompt steers the piped context. The run-level flags are:

• --json reserves stdout for the started run handle JSON only and uses automation-safe fail-fast behavior.
• --detach starts the run without attaching to the live log.
• --headed shows the browser window when browser automation is used.
• --url <url> provides an explicit caller-context URL for one run. It does not force the run to be a web target; the agent still resolves what the URL means from the request and runbook.

The top-level prompt form and the explicit run command are equivalent:

quire "Verify checkout before I approve this PR"
quire run "Verify checkout before I approve this PR"

Run lifecycle operations are top-level verbs: quire status <run-id>, quire watch <run-id>, quire cancel <run-id>, and quire sync <run-id>. The plural quire runs command lists recent runs.

Each run writes a small artifact contract under ~/.local/share/quire/runs/<workspace-key>/<run-id>/ by default:

run/
  status.json
  progress.jsonl
  handoff.md
  evidence/
  .harness-sessions/
    <session-id>.jsonl

Set QUIRE_RUNS_DIR to override the run-artifact root. status.json is Quire-owned operational state: lifecycle status, run metadata, request metadata, sync state, harness-session pointers, and final handoff/result JSON. progress.jsonl is the user-visible narrated timeline that powers quire watch and synced case events. handoff.md is the durable user-facing output. evidence/ contains artifacts referenced by the progress stream or handoff. Harness-native transcripts live in hidden .harness-sessions/ files and are referenced from status.json; they are private implementation state, not the public Quire run ledger.

Local runs use the Pi agent loop on your machine. Quire prefers local Pi/OpenAI Codex provider auth when it is configured, then local GitHub Copilot auth, then Quire Credits through Quire's authenticated broker. Quire-owned provider auth is read from ~/.local/share/quire/model-auth.json by default, with compatibility fallback to Pi's existing auth file. Set QUIRE_MODEL_AUTH_PATH to override the Quire-owned model auth file. quire login associates local runs with your Quire account for identity, wallet access, run upload, and future hosted workflows; personal model-provider auth remains a separate local-provider concern.

The investigation runtime defaults to GPT-5.5 with medium thinking effort for local ChatGPT/Codex auth, local GitHub Copilot auth, and Quire Credits brokered through Cloudflare AI Gateway.

Authenticated runs fetch remote Quire run add-ons at startup. Run add-ons can include an Agent Skills-compatible skill pack, a Quire MCP gateway configured in the web app, and non-authoritative team or user guidance. The CLI-owned run instructions, safety contract, progress protocol, and handoff protocol remain authoritative. Quire includes the agent-browser skill by default, then layers dashboard-uploaded skills on top. The CLI downloads skill ZIPs only when the server hash changes, verifies them, unpacks them under ~/.local/share/quire/skill-packs/, and attaches the unpacked root to Pi through native additionalSkillPaths so skills follow Pi's normal progressive-disclosure behavior. If an MCP gateway is present, the CLI exposes it as the Pi custom tool quire_mcp_call; tool execution is brokered through the authenticated Quire API and is limited to safe allowlisted tools. Run metadata records run-instruction ids/hashes, run add-on ids/hashes, skill pack id/hash/source, and MCP gateway id/hash/tool metadata, not raw prompts, raw skill instructions, resource files, provider credentials, or API tokens.

Use quire connect chatgpt when you want Quire to connect ChatGPT/Codex subscription auth without using the Pi CLI first:

quire connect chatgpt
quire connect chatgpt --no-open

This starts Pi's OpenAI Codex OAuth flow and writes Pi-compatible credentials to Quire's local model-auth store. Existing Pi users do not need this step because Quire still reads Pi's existing auth file as a fallback.

Use quire connect copilot when you want Quire to connect GitHub Copilot subscription auth. Pass --github-enterprise <url-or-domain> for GitHub Enterprise, or omit it for the interactive prompt and press Enter for github.com.

quire connect copilot
quire connect copilot --github-enterprise company.ghe.com
quire connect copilot --github-enterprise company.ghe.com --json

Web investigations use the agent-browser package bundled with @quireco/cli; a separate global agent-browser install is not required. A usable Chrome/Chromium installation is still required for local browser automation unless the run uses an external browser provider or explicit executable path.

Remote agents can use an environment-scoped API token instead of browser login:

export QUIRE_API_TOKEN=qk_...
quire whoami --json
quire run "Verify this PR" --json

API tokens are created in the web app under Settings → API Tokens. The CLI sends them with X-Quire-API-Key, uses QUIRE_API_URL when pointing at a non-production Quire app, and syncs runs under the token's environment name so Cursor Cloud, Codex, and CI activity can be grouped separately from direct human sessions.

For local Quire website/API dogfooding, keep the source default pointed at https://quire.sh and override per command:

vp run @quireco/cli#quire:local whoami
vp run @quireco/cli#quire:local run "verify the local dashboard" --url http://localhost:3000/dashboard

Hosted Model-Source Status

Use quire whoami --json to check the authenticated account and hosted model-source status before relying on remote Quire Credits behavior:

{
  "authenticated": true,
  "user": { "id": "user_123", "email": "[email protected]" },
  "modelSourceBroker": {
    "available": true,
    "status": "available",
    "selectedProviderMode": "quire_wallet",
    "selectedOrder": ["quire_wallet"],
    "reason": "wallet_available",
    "requiredNextAction": null,
    "requiredBalance": 1,
    "remainingBalance": 100,
    "recentUsage": [
      {
        "modelId": "gpt-4.1-mini",
        "status": "succeeded",
        "totalTokens": 13,
        "runId": "run_9x4mdq7p2h8kc6nv4apz",
        "createdAt": "2026-05-18T06:00:00.000Z"
      }
    ]
  }
}

The hosted status is a redacted summary from Quire's server-side model-source API. It does not include provider credentials, sealed envelopes, raw tokens, prompts, or completions. Local quire run can use local Pi/OpenAI auth when configured; Quire Credits and hosted/Slack-triggered execution use Quire-managed billing.