Connecting Your Tools Safely: The Secrets Guide

The vault · values stay masked, everywhere, always

Sooner or later you'll want HQ to actually do things in your other systems, like sending from your email tool, querying your database, or pulling your Stripe numbers. All of those need credentials: API keys, tokens, passwords. HQ calls these secrets, and it has a dedicated, safe way to handle them.

The cardinal rule#

Never paste a secret into the chat. HQ never needs you to.

This deserves emphasis because it's the reflex everyone has: HQ asks for access to something, and you're tempted to paste the API key right into the conversation. Don't. Chat sessions are ordinary text. Pasting a key there is like writing your password in a notebook. Every legitimate way HQ uses secrets works without the secret ever appearing in a conversation: you enter values into a hidden prompt or a secure webpage, and HQ passes them invisibly to the programs that need them. If anything ever seems to require pasting a credential into chat, stop. There is always a proper path, and this article shows each one.

Where secrets live#

Secrets are stored in an encrypted cloud vault (HQ's secure online storage, which uses AWS's parameter store under the hood), with a short-lived encrypted cache on your machine so repeated use is fast. Access requires being signed in (/hq-login).

Every secret has one of two scopes:

• Company scope: belongs to a company (your team's isolated workspace). Shareable with teammates through per-secret permissions. Use this for anything the team needs: the shared Stripe key, the production database password.
• Personal scope: belongs to you alone, visible to nobody else, no sharing at all. Add --personal to any command. Use this for your own GitHub token or a personal API key.

Rule of thumb: if a teammate could ever legitimately need it, make it a company secret and share it; if it's genuinely yours alone, --personal.

Secret names are uppercase with underscores, optionally grouped with slashes: STRIPE_SECRET, PROD/DB_PASSWORD.

Adding a secret (three safe ways)#

1. Type it into a hidden prompt. In a terminal:

hq secrets set STRIPE_SECRET

It prompts you for the value; what you type is never shown on screen and never enters the chat. Add --personal for a personal-scope secret.

2. Ask HQ to make you a one-time link. This is the best path when HQ (or a teammate) needs a credential that only you have. The AI should never see it, and now it doesn't:

hq secrets generate-link STRIPE_SECRET --expires 4h

That produces a single-use secure webpage. You (or whoever holds the credential) open the link, paste the value into the page, and it goes straight into the encrypted vault. The conversation, the AI, and anyone reading the session never see it. Links expire (24 hours by default, up to 7 days) and work exactly once. This is also the safe way to hand credentials over: instead of a teammate texting you a password, send them a link.

3. Pipe it from a script, for the technically inclined: hq secrets set NAME --from-stdin.

How secrets get used (you'll barely notice)#

Here's the payoff for doing it right: when HQ runs something that needs a credential, it injects the secret invisibly into just that program, just for that run.

hq secrets exec --only STRIPE_SECRET -- node billing-report.js

The --only part names exactly which secrets the program gets. Nothing else leaks in. The value goes straight from the vault into the program's environment; it never appears in HQ's output or your conversation.

For code projects, there's an even smoother version: if a repository includes a .env.schema file declaring what it needs, then

hq run -- npm run dev

fetches every declared secret in one go and starts the app with them in place. No lists to maintain, nothing printed, nothing pasted. (Builders: see the hq-secrets skill reference for the schema format.)

You can always see what exists without exposing anything. hq secrets list shows names and metadata only, and hq secrets get NAME shows metadata with the value redacted.

Sharing a company secret with teammates#

Company secrets start restricted to whoever created them. Grant access deliberately:

hq secrets share PROD/DB_PASSWORD --with alice@yourco.com --permission read

Permissions are read (can use the value), write (can update it), and admin (can also manage who has access). For teams, share with a group instead of individuals. Then onboarding a new hire is just adding them to the group. Check who has access anytime with hq secrets acl PROD/DB_PASSWORD, and revoke with hq secrets unshare ... --from ....

Checking for leaked secrets: hq scan secrets#

Before you commit, run:

hq scan secrets

It checks your staged changes, or the files you name, for keys and tokens. It runs offline and needs no account. For each hit it shows the rule, the file, and the line. It never prints the secret itself.

It exits with 0 when nothing is found, 1 when it finds a possible secret, and 2 when it couldn't run.

Scanning every commit automatically

You can have HQ run this scan for you on every git commit on your computer. It's off by default. To turn it on, run this from your HQ folder:

bash core/scripts/commit-secret-scan.sh enable

From then on, a commit that contains a possible secret is stopped before it's saved. It works in all your repos, and any commit checks your repos already had still run after the scan. To turn it off again, run the same command with disable in place of enable, which puts your old settings back. /hq-checkup reminds you to turn it on while it's off.

Separately, /review always scans the files a branch changed before a pull request, whether or not commit scanning is on. Anything it finds blocks the pull request until you remove the value, store it in the vault with hq secrets set, and rotate it if it was ever pushed.

If a line is a known false alarm, add a gitleaks:allow comment to it.

Common questions#

If you get stuck#

The usual culprit is authentication: run /hq-whoami, then /hq-login if needed, and retry. A "permission denied" on a company secret means you need someone with admin on that secret to hq secrets share it with you. Anything stranger: /hq-bug, or the "I'm stuck" guide.