Skip to content
Indigo HQ Docs

hq-cli

hq-cli ships the hq command — the ongoing management CLI for an HQ instance. It is published to npm as @indigoai-us/hq-cli (currently 5.x).

What it is

  • The operator-facing CLI: “HQ by Indigo management CLI — modules and cloud sync.”
  • Provides the hq binary (plus an hq-auth-refresh helper).
  • Built on Node ≥22, ESM + TypeScript, Commander 12. Depends on @indigoai-us/hq-cloud for sync.

The public seed-mirror may show an early placeholder version (e.g. 0.1.0). The current, canonical CLI is @indigoai-us/hq-cli 5.x — that’s the one to install.

Who uses it / when

Everyone operating an HQ instance from the terminal. After hq-core scaffolds the directory, the hq CLI is how you manage modules and drive cloud sync day to day.

Key commands

Terminal window
# module management
hq modules list             # show module inventory
hq modules add <repo-url>   # clone + register a module
hq modules sync             # update all modules to pinned commits


# cloud sync (delegates to @indigoai-us/hq-cloud)
hq sync init                # authenticate
hq sync start               # start background sync
hq sync status              # health
hq sync stop                # stop background sync
hq sync doctor --reconcile-conflicts [--yes]   # clean up legacy .conflict-* twins (dry-run by default)


# vault files
hq access <path-or-query>   # can't find or open a file? never-existed / not-synced (fetched) / no-access (asks the owner)


# packs (content packs)
hq install @indigoai-us/hq-pack-<name>   # install a content pack
hq packs list                            # installed packs + the curated catalog
hq packs update [name]                   # re-install the latest (--check-only to peek)
hq packs uninstall <name>                # un-wire + archive a pack cleanly


# capabilities
hq run / hq secrets exec                 # schema-driven secret access


# Fleet Agents
hq agents provision "Fleet Scout" --company acme --size power
hq agents list --company acme


# work mesh (native REST + ~/.hq/work-mesh/cache — no pack helper)
hq mesh check --company <slug>           # active project threads
hq mesh start --project <slug>           # claim / report start
hq mesh progress --project <slug> --summary "<text>"
hq mesh doctor                           # warm directory, inbox, pair DMs


# historical meeting transcripts
hq meetings import <transcript.json> --company <slug>

hq sync doctor --reconcile-conflicts reconciles the sibling <file>.conflict-<timestamp>-<machine>.<ext> twins that earlier engine versions left beside live files. It is a dry-run by default and prints a plan; --yes applies it. A twin is promoted only when its frontmatter version: is strictly higher than the live file’s — otherwise the live file is kept — and every losing or orphaned copy is parked under .hq/conflict-backups/. See Cloud Sync for how current conflicts are decided.

hq access <path-or-query> (5.109+) is the one command for “I can’t find or open this file.” It resolves an exact vault key or a fuzzy name (it never auto-picks between several matches), then reports exactly one outcome: never-existed (exit 2), local/not-synced (exit 0), or no-access (exit 3). When the file exists and you can read it but it is not on disk, it fetches and pins it the same way hq files get does, repairing sync with hq sync doctor and retrying once if the fetch fails. When you lack access it names the grantor, shows their email, asks one yes/no question, and sends them a DM whose copy-prompt is the exact hq files share … --permission read command; repeat requests for the same prefix are deduped for 24 hours. --json never sends without --yes; --no-fix diagnoses only. Every access-denied error from hq files … and hq sync … now ends with Run: hq access <path>. See hq-share.

Pack commands accept --json for machine-readable output — the hq-sync menubar app uses this to power its Packages window.

Fleet Agent creation accepts --size basic, --size power, or --size dev. Before provisioning, the CLI prints the selected capacity and company-specific monthly price and asks for confirmation. See Create an agent and Agent sizes and billing.

hq meetings import lets a company owner add a normalized historical transcript to the company knowledge pipeline. The JSON file identifies the company, recorder, source, participants, provenance, timestamps, and timestamped transcript segments. Imports are immutable by externalSourceId: submitting the same file again reports unchanged, while submitting different content with the same ID reports a conflict instead of overwriting the original. Imported meeting paths are pipeline-managed and remain excluded from ordinary hq sync push uploads.

Structured identity and access checks

HQ CLI 5.109.7 adds structured output for scripts that verify a project handoff:

Terminal window
hq whoami --json
hq people resolve teammate@example.com --company acme --membership-only --json
hq files acl projects/example/ --company acme --json

whoami --json reports the selected identity and authentication state without printing tokens. people resolve --membership-only checks current company membership instead of relying on a local directory entry. files acl --json separates direct grants, inherited grants, and child entries; exists: false means the requested path has no direct ACL row, not that access is denied.

For a handoff, match the intended company, exact prefix, recipient, and permission. A successful sender-side check does not prove the recipient can open the files; confirm pickup with the recipient separately.

How it composes

hq-cli handles two concerns: module management (the module system) and cloud sync. Sync subcommands lazily import("@indigoai-us/hq-cloud") only when invoked, so module commands work even without the cloud engine present. The same engine is also driven by the hq-sync menubar app.