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 for HQ. It covers about 70 top-level commands: sync and cloud, packs and modules, files and access, secrets, agents and bots, DMs, meetings, integrations, billing, deploy, work mesh, lanes, and more. The full list is in the hq CLI reference.
  • Provides the hq binary (plus an hq-auth-refresh helper).
  • Requires Node ≥20 (engines.node in package.json); ESM + TypeScript, Commander 12. Depends on @indigoai-us/hq-cloud for sync. (The create-hq installer has a higher floor, Node ≥22.13.)

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 sign in, sync, install packs, and work with vault files, secrets, and agents from the terminal.

Key commands

Terminal window
# module management
hq modules list             # show module inventory
hq modules add <repo-url>   # register a module in the manifest (does not clone)
hq modules sync             # clone or update all modules to pinned commits


# sign-in and cloud sync (delegates to @indigoai-us/hq-cloud)
hq login                    # sign in through Cognito (--provider google|microsoft|picker)
hq cloud provision company <slug>   # make a local company cloud-backed
hq sync now                 # push local changes, then pull remote updates
hq sync push                # push only
hq sync pull                # pull only
hq sync status              # local sync journal summary
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 github:indigoai-us/hq-packages#packages/<pack>   # 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 medium
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), no-access (exit 3), or ambiguous (exit 4, several keys matched). 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.

hq install also accepts a bare slug, which resolves through the HQ marketplace, an npm @scope/name[@version], a git URL, or a local path. The github: form above is what core/core.yaml uses for recommended packs.

Pack commands accept --json for machine-readable output. The HQ desktop app uses it for Library → Installed.

Fleet Agent creation takes --size. The accepted names depend on the company’s size ladder. Companies on usage pricing (accounts created from 16 October 2026) use small, medium, large, or xlarge; there the legacy names basic, power, and dev also work and map to small, medium, and large. Companies still on the earlier ladder use basic, power, or dev. The CLI refuses a size the company’s ladder does not offer. 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 is a broad CLI, not only module management and sync. Sync and cloud commands call the @indigoai-us/hq-cloud engine, which is a dependency of the CLI. The same engine is also driven by the HQ desktop app. Module management uses the module system. For every command and subcommand, see the hq CLI reference.