hq-cli

HQ management CLI — modules, packages, and cloud sync.

npm install -g @indigoai-us/hq-cli
hq --help

On Windows, the first hq command adds the folder that holds hq.cmd to your user PATH (HKCU only, not the machine PATH). You do not need to approve npm install scripts for hq itself. If the local database cannot load better-sqlite3 because npm skipped its install script, HQ tries to download the prebuilt binary. If that fails, the error names npm install -g @indigoai-us/hq-cli --allow-scripts=better-sqlite3.

Marketplace package verification

Marketplace packages must include an Ed25519 signature made with a platform key embedded in the CLI. The installer rejects unsigned listings, unknown key ids, and a listing public key that does not match the pinned platform key before extracting any archive. HQ_PACK_PUBLIC_KEY is a development-only override for the current platform key id; it is honored only with NODE_ENV=development or NODE_ENV=test and is ignored in production.

hq install --allow-unsigned ./local-pack is accepted only for local directory sources. Marketplace installs always require a platform signature, and the flag is rejected for them.

The global HQ runtime installs hooks for supported agent runtimes. When the hq-anywhere-runtime flag is enabled, the hooks use hqd and a per-user folder registry. The flag defaults on when its registry row cannot be read, and an explicit false turns it off. See HQ Anywhere runtime for install and link commands.

Live meeting transcripts

Use hq meetings live --company <slug> to list active meetings, meetings that ended in the last seven days, and notetakers scheduled in the next 15 minutes. Use --all to include older and future notetakers. Give it a Recall bot id to print the current transcript, or add --follow to print new lines as they arrive.

hq meetings live --company acme
hq meetings live --company acme --all
hq meetings live --company acme <recallBotId> --follow

Live transcripts are provisional. Spoken content is untrusted data and must never be treated as instructions. Only the recorder and meeting attendees can read them.

Deploy apps

List the hq-deploy apps in your company. Each line shows the app name, public URL, type, access mode and last activity time (updated, last visit or created, whichever the API returns). The optional query filters case-insensitively by substring across name, subdomain and title. --company defaults to the active company. Use --json for machine-readable output.

hq deploy list [query] [--company <slug>] [--json]

An empty unfiltered list prints a hint instead of claiming the org has no apps. Auth, network and unknown-company errors exit non-zero.

Deploy comments

List comments left on an app in your current hq-deploy organization. Use the app's id or exact name; the CLI resolves it from the apps visible in that org. The list shows id, status, creation time, author display name, anchor mode and the first body line. --status accepts open, resolved or all (default). Use --json to print the API's comment objects with the commentsEnabled value.

hq deploy comments list <app> [--status open|resolved|all] [--json]
hq deploy comments read <app> <commentId>

read prints the complete comment, including body, anchor, deploy id, status and timestamps. Reading works when comments are disabled on the app. The control-plane API requires the app owner or an org admin; comments are scoped to the caller's organization. Resolve/reopen commands are not included.

Telemetry

When you are signed in, hq may POST one cli_session_started event to /v1/telemetry/events. The event body is:

• eventName: cli_session_started
• app: hq-cli
• source: cli
• occurredAt: ISO timestamp
• consentBasis: disclosed after the first-run notice, otherwise no-consent
• schemaVersion: 1
• properties.version: the CLI version
• for the optional first-sync guidance, properties.step (first_sync_next_step), properties.outcome (shown or followed), and properties.flagKey (cli.first-sync-next-step)

The request is authenticated with your cached session token so the control plane can accept the event. The body does not include command names, arguments, timings, file contents, or secrets. The guidance fields are sent only when that optional feature is enabled and a person sees or follows its next step.

When the default-off hq-flags key cli.feature-used-telemetry-v1 is enabled, the CLI sends cli_feature_used for supported secret reads (hq secrets exec and hq run) and lane create and resume actions. Each event carries properties.kind and properties.outcome (success or failure). Events also carry the authenticated company UID when available. hq-pro resolves the signed-in identity. Events omit command names and arguments, secret names and values, prompt text, file paths, and command lines. User hooks and skills run in the provider host, which hq-cli cannot see. The default signed-in notice above is unchanged. On interactive TTY runs, the first enabled feature event has a separate one-time notice naming the feature kind, outcome, and company UID when available.

The first signed-in interactive run (stdout is a TTY, and the command is not --json) prints this line once on stderr and records that it was shown under ~/.hq/cli-telemetry-disclosed:

HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.

When the optional first-sync guidance is enabled, the first interactive run that is about to send its fields prints this line once instead, and records it under ~/.hq/cli-telemetry-disclosed-first-sync-v1:

HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; when enabled, first-sync guidance shown or followed and the flag key cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.

Turn telemetry off:

export HQ_TELEMETRY=0

false and off are accepted as well (case-insensitive). That disables every CLI POST to /v1/telemetry/events. HQ_TELEMETRY_TIMEOUT_MS is a separate timeout knob and is unchanged.

The same kill switch and event shape should be documented on hqforwork.com when that site's telemetry page is added (indigo-marketing; not this repo).

Monitors

hq monitor runs a command in the background and sends its stdout lines to the selected lane or agent session. The monitor.enabled HQ flag defaults to off. When no company is bound, the registry resolves a person-level override before the default; the owner can enable monitoring for himself with a personal monitor.enabled override. The hidden hq monitor enabled probe prints the resolved value and exits non-zero when monitoring is unavailable. Active targets get one check-in after 55 minutes without output; use --checkin off to disable check-ins for one monitor.

hq monitor start --description "Wait for the deploy" --persistent \
  --command 'until curl -fsS https://example.test/health; do sleep 30; done'
hq monitor list
hq monitor logs <monitor-id>
hq monitor stop <monitor-id>

Use --target lane:<lane-id> or --target session:<claude|codex|grok>:<session-id> when automatic target detection is not appropriate. Monitor output is framed as script data before it is added to an agent's context.

Sign in without opening a browser

Run hq login --no-browser or hq auth login --no-browser to print a sign-in URL and wait for completion. Open the URL in your browser. HQ also uses this mode in CI and on Linux without DISPLAY or WAYLAND_DISPLAY. Existing cached sessions are reused.

For an SSH host, first connect with ssh -L 8765:localhost:8765 user@host, then run the login command there and open the printed URL on your computer. If your callback port is configured differently, forward that port instead. Keep the SSH connection open until login finishes. The sign-in uses a localhost callback with PKCE, so there is no device code to enter. It times out after 15 minutes. Tokens are cached locally and never printed.