AI Workforce OneHQDocs

Sign in

hq login signs this computer in with a one-time code that you type into HQ in your browser. No password or key ever passes through the terminal.

Sign in

  1. Run hq login

    It asks HQ for a one-time code, prints it, and opens the approval page in your browser.

    Opening https://hq.aiworkforceone.com/device?code=BCDF-GHJK
If your browser did not open, go to https://hq.aiworkforceone.com/device and enter:

    BCDF-GHJK

This computer: my-laptop (hq 0.2.0, macOS arm64)
Waiting for approval (code expires in 10 min, Ctrl-C to cancel)...
  2. Approve it in HQ

    Sign in to HQ if you are not already, then type the code from your terminal. The page never fills it in for you, so a link someone else sent you cannot approve their computer. Check that the computer name and system match yours, pick the organizations it may reach, and confirm with your password or your two-factor code.

  3. Back in the terminal

    hq notices the approval within a few seconds:

    Logged in as you@example.com · access renews automatically on this device
Orgs: Acme (acme)
The code expires after 10 minutes.

Run hq login again for a new one. Denying the request in the browser ends the login at once.

Where the login is kept

  • macOS: your login keychain.
  • Linux: the Secret Service (for example GNOME Keyring) when secret-tool is installed and a keyring is running.
  • Windows, or Linux without a Secret Service: ~/.hq/credentials.json, readable only by you. hq tells you when it uses this file. Set HQ_KEYCHAIN=file to choose it yourself.

The keychain protects the login with your user account, not per app: any program running as you can read it. What makes a copied login useless elsewhere is the device key hq login creates in ~/.hq/keys/: HQ checks its signature on every request, and each access token lasts 15 minutes.

Check who is signed in

hq status

It prints your email and every team you can reach, with its hq-… name.

Sign in to another HQ address

hq uses, in this order: the --host you pass to hq login, then HQ_HOST if it is set, then the address you last signed in to, and https://hq.aiworkforceone.com the first time. Every other command uses the saved address (or HQ_HOST). The address must use https://.

hq login --host https://hq.aiworkforceone.com

Sign out

hq logout

HQ revokes this computer in every organization, and hq removes the stored login.

If it fails

MessageWhat to do
hq: the login was denied in the browser.Someone chose Deny. Run hq login again.
hq: this login code expired. Run hq login again.The 10 minutes ran out. Start over.
hq: remote access is not available on this HQ yet.This HQ address does not offer CLI sign-in. Check the address.

More in Troubleshooting.