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

Workspace target (quire env)

quire env manages the workspace target that tells Quire what application to investigate. Configure the default target once, then investigate will pick it up automatically:

quire env init --web                                      # prompt for a web target
quire env init --web --base-url http://localhost:3000     # non-interactive web target
quire env init --mobile --ios                              # scaffold a mobile target
quire env                                                  # print the resolved target
quire env --json                                           # machine-readable form

quire env set platform=ios provider=local appId=com.example.app
quire env set kind=mobile platform=android                 # switch web → mobile
quire env unset device

Named environments live under .quire/environments/<name>.json and are selected with --env:

quire env init --web --env local
quire env init --web --env prod --base-url https://app.example.com
quire "Verify checkout" --env prod

set accepts one or more key=value pairs and validates the result against the schema before writing. Valid keys depend on kind:

• Web: baseUrl
• Mobile: platform (ios/android), provider, device, appiumUrl, url, appId, appPath

Setting kind=mobile (or kind=web) switches the union shape and drops incompatible fields. Use quire env init --force to start over from a stub.

Doctor

quire doctor diagnoses the current setup before you start an investigation. It checks identity (auth + model broker), workspace (.quire/environment.json + target reachability), 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, target.web.reachable, target.mobile.device) 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.

Target reachability runs by default: web environments are probed with a HEAD request, iOS local environments check xcrun simctl list devices booted, Android local checks adb devices, and Appium providers ping /status.

Investigations

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

quire "Reproduce the checkout crash"
quire ask "Verify the login page loads"
quire investigate "Reproduce the checkout crash"

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

quire investigate "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 investigate "Reproduce the checkout crash" --json
cat issue.md | quire investigate --stdin --json
quire report <run-id> --wait --json

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> --stdin --json

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

investigate carries a deliberately small flag surface — everything that describes the target (platform, provider, device, app id, etc.) lives in .quire/environment.json via quire env. The run-level flags are:

• --stdin reads plain-text investigation context from stdin. If a positional prompt is also present, stdin is treated as additional context.
• --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.
• --watch attaches to the live run log after starting the investigation. Human mode watches by default; this is mainly useful with --json. Ctrl-C detaches.
• --headed shows the browser window for web targets.
• --url <url> overrides the configured web baseUrl for one run.
• --env <name> uses .quire/environments/<name>.json instead of the default .quire/environment.json.

Top-level shortcuts mirror the most common run subcommands:

quire watch <run-id>          # alias for `quire runs watch`
quire report <run-id>         # alias for `quire runs report`
quire handoff <run-id>        # alias for `quire runs handoff`

Less common run operations stay under the canonical runs namespace: quire runs status|cancel|list ....

Each run writes metadata.json, report.json, handoff.md, and raw emit-report.json under ~/.quire/runs/<workspace-key>/<run-id>/ by default. Set QUIRE_RUNS_DIR to override the run-artifact root. Runs also store a local Pi session under the run directory so quire continue can resume prior context without syncing raw prompts, completions, or provider credentials.

report.json is the structured source of truth. The stable top-level fields include:

• triage, summary, confidence, and likelyCause
• evidence[] with optional run-local artifact paths
• reproductionSteps[] and journeysTried[]
• environment.notes[] and environment.blockers[]
• codeReferences[] with likely edit targets, optional symbols/lines, rationale, and confidence
• verification.commands[] and verification.manualSteps[] with expected outcomes
• recommendedActions[] and suspectedFiles[] for backwards-compatible summaries

Use quire runs report <run-id> --wait --json when another agent needs the full structured payload. Use quire runs handoff <run-id> --wait when a human or coding agent needs a compact markdown brief with summary, evidence, likely source files, verification commands, and a ready-to-use next prompt.

Local investigations run the Pi agent loop on your machine. Quire prefers local Pi/OpenAI Codex provider auth when it is configured, then falls back to Quire Credits through Quire's authenticated broker. Quire-owned provider auth is read from ~/.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 both local ChatGPT/Codex auth and Quire Credits brokered through Cloudflare AI Gateway.

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.

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 investigate "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.

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_123",
        "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 investigate can use local Pi/OpenAI auth when configured; Quire Credits and hosted/Slack-triggered execution use Quire-managed billing.

Example web environment (write with quire env init --web and edit via quire env set):

{
  "version": 1,
  "app": { "kind": "web", "baseUrl": "http://localhost:3000" }
}

Example mobile environment:

{
  "version": 1,
  "app": {
    "kind": "mobile",
    "platform": "ios",
    "provider": "local",
    "appId": "com.example.app"
  }
}