Skip to content
Indigo HQ Docs

hq-share

hq-share is a capability of the hq CLI, not a standalone repo. It grants access to prefixes in the hq-pro vault.

hq-share mints an encrypted, single-use share-session link for one or more HQ vault prefixes. The CLI opens a share-session page in your browser where you pick recipients (humans, active HQ agents, groups, or “Share with All”) with per-recipient read/write, then submits every grant in one round-trip.

Usage

/hq-share <path>... [--with <principal>] [--permission read|write] [--company <slug>] [--no-open] [--no-draft]
Terminal window
/hq-share 'reports/q3/*'                                     # everything under reports/q3/
/hq-share 'reports/q3/*' 'docs/handbook/*' --company indigo
/hq-share 'announcements/*' --no-open                        # print URL only (headless contexts)
/hq-share 'reports/q3/*' --no-draft                          # skip the drafted note step
/hq-share 'invoices/*' --with grp_finance --permission read  # direct grant, no browser

Path patterns follow the vault ACL conventions:

  • prefix/* shares everything under the folder, recursively. Quote it so the shell does not expand the *.
  • A trailing slash (reports/q3/) is a private folder: it lets the recipient create files directly inside it but does not grant access to any existing child.

Prefixes are relative to the company vault; do not prepend companies/<slug>/. --with selects the direct-grant path (see below); without it, /hq-share runs hq files share <paths...>, which mints the token and opens the picker.

From HQ MCP

HQ MCP exposes the same vault sharing backend through the hq_files_share MCP tool. Ask ChatGPT or Claude.ai to share a company file or prefix after the connector is installed.

  • Omit with to mint a short-lived share-session URL for the browser picker.
  • Set with to a human or agent email, prs_* person UID, agt_* agent UID, grp_* group ID, or @all for a direct grant.
  • permission defaults to read; use write only when the recipient should be able to edit.

See HQ MCP for the full MCP tool surface.

How it works

  1. Auth check — requires a signed-in session (~/.hq/cognito-tokens.json); run sign-in first if absent.
  2. Confirm scope — the resolved paths and company are echoed back before minting, because granting on the wrong company is hard to undo.
  3. Mint + open — the CLI prints the share-session URL, the normalized paths, and an Expires: timestamp, and opens the picker page.
  4. Pick recipients — choose humans, active agents, groups, or “Share with All” and per-recipient read/write; all grants submit in one batch. Agent selections are stored under their stable agt_* identity.

Default token TTL is 15 minutes. hq files share --expires accepts up to 24h (for example --expires 1h); the server accepts 60s–7d for other callers.

Single-use capability URLs

A share-session URL is a live, encrypted, single-use capability: any holder can redeem it to write ACLs in the issuer’s name. Handle it accordingly:

  • At mint time it is surfaced once, only as a Markdown inline link whose label carries purpose + expiry and whose href carries the token — never as bare visible text.
  • It is never echoed again in any later turn, summary, commit message, PR body, journal, or other persisted artifact. Everywhere after minting, use the redacted form https://hq.computer/share-session/<TOKEN_REDACTED>.
  • Tokens are single-use — if a recipient hits expired (403) or nonce_already_claimed (409), mint a fresh link rather than extending the old one.

This page intentionally shows only the redacted placeholder. Real share-session tokens never appear in documentation.

Direct grants vs. the browser flow

For a single recipient or scripted grants, prefer the direct form:

Terminal window
hq files share <prefix> --with <principal> --permission <read|write>
hq files share <prefix> --with @all --permission read   # company-wide

The browser flow is the better fit when granting multiple recipients at once. Widening anyone to write is a privilege escalation — confirm with a human first.

Requesting access

Sharing has a receiving side. When a teammate hits a file they cannot find or open, they run:

Terminal window
hq access <path-or-query>

It tells them which of three things is true and fixes what it can: the file was never created; it exists but is not on their machine (it fetches and pins it, repairing sync if the fetch fails); or it exists and they lack a grant. In the last case it names the grantor (the ACL creator, otherwise a company owner or admin), shows the email, asks one yes/no question, and sends that person a DM whose copy-prompt is the exact hq files share <prefix> --with <email> --permission read command — the grantor pastes it and the request is done. Repeat requests for the same prefix are deduped for 24 hours. Every 403 from hq files … or hq sync … ends with Run: hq access <path>. Requires @indigoai-us/hq-cli ≥ 5.109.0; in an agent session the same ladder is available as /hq-access.

Who can mint

Owners and admins resolve to admin on any prefix and can always mint. Members and guests need an explicit grant on each requested path, or the server returns 403 Forbidden. A mint failure for an admin usually means a stale auth session — re-authenticate before assuming a permission gap.

Requires

@indigoai-us/hq-cli ≥ 5.12.x for the batch browser flow. Check hq --version.

  • hq-cli — the CLI that ships this capability
  • hq-pro — the vault whose prefixes you’re sharing
  • hq-secrets — schema-driven secret access