hq-files

HQ Files

Manage per-prefix file access controls in the HQ vault via the hq files CLI. Access is scoped to S3 key prefixes within a company vault, controlled by an ACL layer that resolves grants at vend-time. See also hq-secrets for secret-level ACLs and group management.

Requires

• @indigoai-us/hq-cli ≥ 5.142.0 — the first release that preserves the private-folder foo/ pattern and distinguishes it from the shared glob foo/* across direct, browser, ACL, browse, and shared-with-me flows. Older clients rewrite a trailing slash to /*; upgrade before using private-folder ACLs. Check with hq --version; upgrade via npm i -g @indigoai-us/hq-cli@latest.

Commands

Command	Purpose
hq files share <prefix> (no --with)	Browser flow. Mints an encrypted single-use share-session token, opens the share-session page in your default browser, and lets you batch-pick recipients (members, groups, "Share with All") with per-recipient read/write before submitting all grants in one click. Supports multiple paths: hq files share path/a/ path/b/. Use --no-open to print the URL without launching a browser.
hq files share <prefix> --with <principal> --permission <level>	Direct grant. Grant read or write access on a prefix to a person, group, or @all. If no ACL row exists for the prefix, one is auto-created with this grant as its first entry; success message is Created ACL and granted ... instead of Granted ....
hq files share <prefix> --with @all --permission <level>	Company-wide grant. Writes a single ACL entry with granteeType: 'company-wide' covering every active member. Distinct from the legacy open flag (see "Company-wide vs open flag" below).
hq files unshare <prefix> --with <principal>	Revoke a grant on a prefix from a person, group, or @all
hq files acl <prefix>	Show the ACL for a prefix: exact pattern (foo/ private or foo/* shared), creator, grantees, permissions, open/restricted status, your effective permission
hq files browse [path]	Read, no sync. List vault objects under [path] without materializing them locally. Each row is tagged shared-with-you, creator (a creator-only child row), private folder (the foo/ marker), or role-bypass (owner/admin reach only). --personal browses your personal vault.
hq files cat <path>	Stream a single vault object to stdout (or --out <file>) without syncing it. Refuses --out destinations under <hqRoot>/companies/.
hq files search <query>	Case-insensitive path/name search over a company (or --personal) vault listing, no download. --company <slug> required (or --personal).
hq files get <path>	On-demand materialize. Download a file/prefix into local HQ. Default writes in place under companies/<slug>/<path> and registers a pin (see "Pins") so a scoped sync keeps it; --into <dir> writes elsewhere (no pin).
hq files shared-with-me [--company]	List the exact prefixes explicitly shared with you, retaining foo/ private-folder rows separately from foo/* shared globs. Omit --company for a cross-company roll-up. Pure read — owner/admin role-bypass reach is NOT listed (explicit grants only).

All commands accept --company <slug> to target a specific company. If omitted, the CLI resolves the company from your membership.

Access vs. Download (read without syncing)

Vault access and local download are separate. Your access is decided server-side at vend-time (STS credential scope + ACL resolution + owner/admin role-bypass). Download is what a sync materializes onto your local HQ tree, governed per-membership by syncMode (all | shared | custom, set with hq sync mode).

The browse/retrieve commands let you reach a file you have access to without downloading your whole share:

• browse / search / cat read straight from the cloud — nothing lands on disk (except cat --out, which you choose).
• get materializes exactly the path you ask for, on demand.
• hq access <path-or-query> (hq-cli >= 5.109.0) wraps all of this for the "I can't find or open it" case: it reports never-existed / not-synced / no-access, runs get (and pins) when you have access, and asks the grantor otherwise. Agent sessions reach it as /hq-access.

Owners and admins keep full role-bypass access regardless of syncMode — narrowing syncMode only shrinks what a sync downloads, never what you can browse or get. The engine's scope filter is a footprint/UX optimization, not a security boundary: a member who lacks access is still blocked by STS no matter the local filter.

Under the hood, browse/cat/search/get vend through the multi-tenant /sts/vend (company) and /sts/vend-self (personal) routes — never the legacy POST /vend. Company vault keys are company-relative; the CLI speaks the anchored companies/<slug>/… form and translates at the S3 boundary.

Pins (keeping a got file under a scoped sync)

hq files get (default in-place mode) records the materialized prefix in a per-machine pin set at <hqRoot>/.hq/pins.json, keyed by company slug. On the next sync, the runner unions a company's pins into its pull scope — so a file you pulled in shared/custom mode is not pruned as an out-of-scope orphan. Pins only ever widen scope (never narrow), and all mode ignores them (it pulls everything anyway). get --into <dir> writes outside the sync envelope and registers no pin. The file is plain JSON; delete an entry to let the next scoped sync prune that prefix again.

Choosing between direct grant and the browser flow

Situation	Use
Single recipient, one path, you already know the email/group	--with direct grant — one command, no browser hop
2+ recipients, or 2+ paths, or you want to see who already has access	Browser flow — one share-session, one submit
Granting to the entire company	--with @all --permission read (direct) or the browser flow's "Share with All" toggle
Scripted/automated grants	Always direct grant — the browser flow is interactive by design

Prefix Conventions

A prefix is an S3-style path fragment, relative to the company's vault bucket root. The bucket is already scoped to the company — never prepend companies/<slug>/, the company's name, or any other company-identifying segment. A grant on companies/myco/reports/ does not cover reports/ (those are different keys, and the former does not exist in the bucket).

The CLI sends the prefix exactly as typed. There are two deliberately different folder patterns:

• Shared folder glob (reports/q3/*) — grants ordinary read/write access to every object below that folder.
• Private folder (reports/q3/) — creates a private-by-default folder. read lets a grantee see the folder itself, not its children. write lets a grantee create one new direct child, but never list, read, overwrite, or delete children. The first authorized upload locks that child to its creator: a file gets a creator-only exact row and a subfolder gets a creator-only /* row. Other people need an explicit grant on that child row.
• Exact key (reports/q3/summary.pdf) — passed through unchanged.

reports/q3/ and reports/q3/* are mutually exclusive at every depth. The server returns 409 ACL_PATTERN_CONFLICT if either pattern already has its sibling row. A bare prefix without a trailing slash and without /* (for example reports) is an exact key; it does not cover anything below it.

The API rejects prefixes that start with / (returns 400). In a shell, quote a shared glob ('reports/q3/*') so pathname expansion does not turn it into a different local argument. S3-key character constraints (no \0, \n, traversal patterns) are also enforced server-side.

Examples:

• reports/ → private folder; new direct children become creator-only
• invoices/2025/* → shared folder glob; grants access to all matching keys
• README.md → grants access to exactly that key
• reports (bare, no slash, no *) → grants access to only the key literally named reports — almost certainly not what you want for a folder

Permission Model

Each ACL entry grants one of two permission levels via the --permission flag. For exact keys and /* shared-folder globs:

• read — caller may list, download, and view metadata for files matching the prefix.
• write — full read plus upload, overwrite, and delete.

For a trailing-slash private folder (foo/), the same words are narrower: read exposes only foo/, and write creates one new direct child only. It does not grant any child read/list/overwrite/delete authority; child access locks to the first uploader until someone creates an explicit child grant.

The CLI accepts only read or write for --permission. The ACL row's creator additionally gets effective admin automatically via creator-bypass at resolution time — visible as Your effective permission: admin in hq files acl output even when no entry grants admin explicitly. Company owners and admins additionally get role-bypass at resolution time — they resolve to admin on any prefix, ACL row or not, so hq files share-session minting works for them even on prefixes they have no explicit grant on.

Who can mutate an ACL:

• Create an ACL row (hq files acl <prefix> with no existing row) or delete one entirely — owner / admin role only. These are structural operations on the row itself.
• Grant a permission within an existing row (hq files share --with) — caller must hold effective permission on the prefix at least as high as the permission being granted (owner/admin auto-pass via role bypass; member must have a grant on that row that gives them ≥ the requested level). Non-bypass roles cannot grant admin — that ceiling is reserved for owner/admin role.
• Revoke a grant (hq files unshare) — caller must hold effective write (or higher) on the prefix. Revoking an admin entry additionally requires owner/admin role (so a member with write cannot nuke admin-level grants on the same row).
• Mint a share-session URL (hq files share <paths>, default flow) — caller must hold effective permission on every requested path (any non-null level). Owner/admin always pass via role bypass; members need an explicit grant. Token is capped at write regardless of caller's effective level.

An ACL may be open (all active members get at least read automatically) or restricted (only explicit entries have access). Most ACLs are created open during the initial backfill; individual grants narrow or extend access on top of the open floor.

Carve-out Denies: when a more-specific prefix exists with no entry for a caller, that sub-tree is denied even if a broader prefix grants access. This is enforced at vend-time (STS session policy), not at the ACL API layer.

Groups as Grantees

--with accepts an email address, a group id matching grp_[A-Za-z0-9_-]+ (letters, digits, underscores, hyphens — e.g. grp_backend-team), or the literal @all for company-wide grants. A group grant extends the permission to every current member. Adding or removing members from the group adjusts who has file access without touching the ACL.

Group management is shared with secrets (same hq groups subcommands). See hq-secrets for hq groups create, hq groups add, etc.

Company-wide vs open Flag

Two ways to give everyone in the company access to a prefix — they look similar but behave very differently:

	--with @all (company-wide entry)	Legacy open: true flag
ACL representation	Explicit row, granteeType: 'company-wide'	Boolean on the ACL header
Audit trail	Visible in hq files acl <prefix> as a regular grant with grantor + timestamp	Just a flag — no grantor, no timestamp
Revoke	hq files unshare <prefix> --with @all	Requires flipping the flag, often via backfill script
New-member propagation	Automatic at vend-time (every active member resolves through the company-wide entry)	Automatic at vend-time
Distinct from per-member entries	Yes — coexists cleanly with named grants	Conflates "everyone has read" with "this is a public folder"

Always prefer --with @all for new company-wide intent. The open flag exists only because most ACLs were created open during the initial backfill — it's load-bearing for legacy data, not the path forward.

Sharing via the Web Page (Share-Session Flow)

When hq files share is run with no --with, the CLI mints an encrypted single-use share-session token and opens a web page where the issuer picks recipients and per-recipient permissions, then submits all grants in one round-trip.

How the token works:

• Encrypted at mint time with the master key (AES-256-GCM, iv || authTag || ciphertext base64url-encoded). The Lambda decrypts on every read; the token is opaque to the browser.
• Pinned scope — the encrypted payload includes the issuer's identity, the requested paths, and maxPermissionByPath computed from the issuer's own ACL. The page cannot grant beyond what the issuer had at mint time, even if the page is mutated client-side.
• Single-use — the page's submit endpoint claims the token's nonce atomically (DynamoDB attribute_not_exists). A successful submit invalidates the token; a second submit returns 409.
• Short-lived — default 15-minute TTL, bounded 60s..7d. The page returns 403 with expired if the token is past its expiresAt.
• Public route, no Cognito session required — the share-session page lives outside the console's authenticated (shell) group at /share-session/[token]. The token is the auth.

Failure modes (operator-visible):

HTTP	Meaning
403 expired	Token TTL exceeded
403 scope_exceeded	Page tried to grant a permission higher than maxPermissionByPath[path] for that path
409 nonce_already_claimed	Token was already redeemed — mint a fresh one
400 invalid_token	Decryption failed — token corrupted or signed under a different master key (e.g. wrong stage)

unshare Idempotency

hq files unshare is safe to call multiple times. When the grant is already absent, the server returns 404; the CLI treats this as a successful no-op — it prints a green "Grant already absent" message and exits 0. Code or automation calling unshare does not need to pre-check whether the grant exists.

Local Write-Access Enforcement (read-only shares)

Vault ACLs are enforced server-side at vend-time, but local HQ sessions also mirror them: the PreToolUse hook enforce-vault-write-access.sh blocks edits, writes, and deletes (Edit/Write/MultiEdit/NotebookEdit and best-effort Bash) under companies/<slug>/ when the local manifest .hq/vault-access.json says your effective permission on that vault path is read-only (or absent). This stops doomed local mutations to read-only shares before the next sync rejects or clobbers them.

• Refresh the manifest after your grants change: bash core/scripts/refresh-vault-access.sh [--company <slug>] (sources: hq files shared-with-me for grants, hq members for your role).
• Fail-open by design: no manifest, an unlisted company, or role owner/admin/unknown means no local enforcement — the server-side STS/ACL layer remains the authoritative boundary.
• Grant matching mirrors the ACL prefix semantics above: *, prefix/* (covers the bare prefix directory too), or an exact key; a private-folder row (prefix/) matches the folder marker only and does not authorize a local child write. The most specific matching grant wins, so a specific read grant carves down a broader write grant. The hook cannot prove the server's first-upload creator decision before a child row exists; create-only private writes therefore must go through an authorized server/CLI upload path, or an explicitly approved bypass, until the creator row is visible in the manifest.
• Bypass requires the user's explicit approval: "HQ_BYPASS_VAULT_WRITE_PROTECT": "1" under env in .claude/settings.local.json — never set it autonomously.

Rules for Agent Workflows

1. Choose the folder pattern deliberately before calling share. Pass reports/q3/* when everyone granted the row should access its children. Pass reports/q3/ when people should only create a direct child that locks to its first uploader. The CLI preserves both forms; a bare reports (no slash, no *) is an exact-key grant that covers nothing inside the folder.

2. Prefixes are bucket-relative — never include the company name or companies/<slug>/. The vault bucket is already scoped to the company; prepending the slug points the grant at a path that doesn't exist. If the user asks you to "share companies/myco/reports/ with X", translate that to reports/ before calling hq files share.

3. Push local files before sharing them. hq files share only creates an ACL row or share-session token; it does not upload local files. If the requested path exists under companies/{company}/, run hq sync push <local-path> --hq-root <hq-root> --company <slug> --on-conflict keep first, then verify the plan/upload count. Treat 0 files to upload on a newly-created folder as a blocker: the path is probably excluded by .hqinclude / .hqignore, or the local path does not map to the bucket-relative prefix you plan to grant.

4. Always confirm the target company. Run hq files acl <prefix> --company <slug> to inspect before mutating. A grant on the wrong company uid is hard to clean up.

5. Verify after sharing. Immediately after hq files share, run hq files acl <prefix> --company <slug> and confirm the displayed pattern is exactly the one intended: /* for a shared folder, / for a private create-only folder, or an exact key. If the sibling pattern already exists, do not retry blindly: resolve the ACL_PATTERN_CONFLICT by choosing the one intended model. To convert an existing sibling, read its entries, unshare every entry (including @all where present), verify the old ACL row is absent, then create the new pattern. If other grants must remain, create a replacement shared/private row only after an owner/admin deletes the empty conflicting row through the ACL delete route; never leave both siblings in place.

6. To share everything in a vault, prefer one grant on * over many per-folder grants. Every vault is provisioned with a * ACL row; granting the principal read on * covers all current and future keys. Per-folder fan-out is fragile (easy to miss new top-level folders) and harder to audit.

7. Prefer group grants for teams. Share reports/* with grp_finance rather than granting each person individually. Membership changes automatically adjust access.

8. Do not widen ACLs without explicit human approval. Granting write on a prefix is a privilege escalation. Always confirm with the human before making these changes.

9. Check your effective permission before attempting mutation. hq files acl <prefix> shows Your effective permission: in the output. Granting requires that effective level be ≥ the permission you're granting (owner/admin always pass via role bypass; non-bypass roles cannot grant admin). Revoking requires effective write or higher, plus owner/admin role for revoking admin entries. Creating or deleting the ACL row itself is owner/admin-only.

10. Do not confuse private folders with shared globs. reports/q3/summary.pdf covers one file; reports/q3/* shares every child; reports/q3/ lets a writer create one direct child that then becomes creator-only. reports/q3/ and reports/q3/* cannot coexist.

11. Carve-out awareness. If a broad prefix (reports/*) is open and you also need to restrict reports/q3/* for a subset of members, that narrowing is expressed as a more-specific ACL with fewer grants — the vend layer automatically denies the sub-tree for callers without a matching entry. Do not attempt to revoke a broad grant to achieve narrowing; instead, ensure the more-specific prefix has the right entries.

12. Use the browser flow for 2+ recipients or 2+ paths. A single share-session page handles N×M grants in one human action — N CLI calls is friction, error-prone, and produces a noisy ACL audit trail. Reserve direct --with grants for single-recipient/single-path or scripted automation.

13. Prefer @all over the legacy open flag for new company-wide intent. Explicit granteeType: 'company-wide' rows are auditable, individually revocable, and don't conflate "everyone has read" with "this folder is public." See "Company-wide vs open Flag" above.

14. Treat share-session URLs as live capabilities — render as Markdown at mint, never persist them. A share-session URL is an encrypted, single-use, 15-minute capability that any holder can redeem to write ACLs in the issuer's name. At the minting turn, surface it only as a Markdown inline link — [Open share-session link — expires <ts> ›](https://hq.{co}.com/share-session/<token>) — never as bare visible text, and never with the token in the visible label (rule: core/policies/hq-secure-link-render-as-markdown.md). Beyond that turn, do not paste share-session URLs (bare or as a Markdown href) into:

    • Auto-checkpoint thread files (workspace/threads/)
    • Journal entries, learnings, or session logs
    • Git commit messages or PR descriptions
    • Slack, email, or any chat surface other than the intended human recipient
    • Worker handoff payloads
    • Any subsequent assistant turn that summarizes or revisits the action

    When demonstrating the flow in documentation, redact the token segment as https://hq.{co}.com/share-session/<TOKEN_REDACTED>. The 15-minute TTL is a defense in depth, not a license to log them.

15. Mint fresh URLs rather than re-sending stale ones. If a recipient says "the link doesn't work," mint a new one — do not extend TTLs server-side or attempt to debug an expired token. Mint cost is one round-trip; a stale token can mask scope drift if the issuer's permissions changed since mint.

Common Workflows

Share via the browser (multi-recipient or multi-path)

# If the folder was created locally, upload it first; sharing only writes ACLs.
hq sync push companies/myco/reports/q3/ --hq-root ~/HQ --company myco --on-conflict keep

# Opens default browser to a share-session page; pick recipients + permissions, click Submit.
# These explicit globs share the existing trees.
hq files share 'reports/q3/*' 'docs/handbook/*' --company myco

# Print the URL without launching a browser (useful in headless contexts)
hq files share 'reports/q3/*' --no-open --company myco
# → Share-session URL generated:
#     https://hq.myco.com/share-session/<TOKEN_REDACTED>
#     Paths:   reports/q3/*
#     Expires: 2026-05-12T03:34:16Z

Share a folder with the entire company (@all)

hq files share 'announcements/*' --with @all --permission read --company myco
# → Granted read on announcements/* to @all (granteeType: company-wide)
#   This is a shared folder: recipients can read every object under announcements/.

# Revoke later — single ACL row, single command
hq files unshare 'announcements/*' --with @all --company myco

Share the entire vault with a teammate

hq files share '*' --with alice@example.com --permission read --company myco
# → Granted read on * to alice@example.com
hq files acl '*' --company myco
# Confirm alice@example.com appears in Entries with permission=read

Share a folder with a teammate

hq files share reports/q3/ --with alice@example.com --permission read --company myco
# → Granted read on reports/q3/ to alice@example.com

# Always verify — this is a private folder, not a shared glob
hq files acl reports/q3/ --company myco
# ACL for reports/q3/ (private folder, restricted)
# Children remain creator-only; use reports/q3/* when the recipient needs them.

Share a folder with a team group

hq files share 'invoices/*' --with grp_finance --permission read --company myco

Give write access on a subfolder

hq files share 'uploads/inbox/*' --with bob@example.com --permission write

Revoke access

hq files unshare reports/q3/ --with alice@example.com --company myco
# → Removed grant for alice@example.com on 'reports/q3/'

Revoke a grant that may or may not exist (idempotent)

hq files unshare reports/q3/ --with alice@example.com
# → Grant already absent for 'reports/q3/' / alice@example.com   (exits 0)

Inspect an ACL

hq files acl reports/q3/ --company myco
# ACL for reports/q3/ (private folder, restricted)
# Creator: person_xxx
# Your effective permission: read
# Children are creator-only; use reports/q3/* for a shared folder.
# Entries:
# TYPE   GRANTEE              PERMISSION  GRANTED_BY   GRANTED_AT
# email  alice@example.com    read        person_xxx   2025-09-01
# group  grp_finance          read        person_xxx   2025-10-12

Create a group and share a folder with it

hq groups create grp_backend-team --name "Backend team"
hq groups add grp_backend-team alice@example.com
hq groups add grp_backend-team bob@example.com
hq files share 'services/logs/*' --with grp_backend-team --permission read

Error Reference

HTTP Status	Meaning
400	Bad request — invalid prefix, invalid permission, or PolicyNestingUnrepresentable (3+ nesting depth would produce an unrepresentable IAM policy)
401	Not authenticated — run hq login
403 Forbidden: owner or admin role required	Creating or deleting an ACL row, or you tried to grant 'admin' as a non-bypass role
403 Forbidden: caller lacks '<perm>' on '<prefix>'	Granting/revoking but your effective permission on the prefix is below the requested level (members need a grant ≥ what they're handing out; revoke needs write+)
403 Forbidden: only owner or admin role may revoke 'admin' entries	Member with write tried to revoke an entry whose permission is admin — that ceiling is reserved for owner/admin role
404	For acl: no ACL record exists yet for this prefix. For unshare: grant already absent — the CLI converts this to a no-op and exits 0. share no longer surfaces 404 (the row is auto-created on first grant).
409 ACL_PATTERN_CONFLICT	A private folder (foo/) conflicts with its shared-glob sibling (foo/*). Keep the one access model you intend; they cannot coexist.
other 409	Concurrent modification — retry
any 403 on a read (browse, cat, get, search)	You lack a grant on that exact prefix. Every 403 ends with Run: hq access <path>; run it (or /hq-access) to confirm the file exists, and to ask the grantor for read access with one confirmation.
5xx	Server error

When share returns 400 PolicyNestingUnrepresentable, the ACL write is rejected because granting the principal both a broad allow AND a nested allow (with a carve-out Deny in between) would produce an IAM policy exceeding the representability limit. Resolution: grant the principal at the intermediate prefix first (hq files share <carve-out-prefix> --with <principal> --permission read), then retry the nested grant.

See also

• /hq-access — a teammate cannot find or open a path: diagnose (never existed / not synced / no access), self-heal, and ask the owner for a grant
• /hq-share — mint a single-use share link
• /hq-secrets — same vault, for secrets