# 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 [#sign-in]

<Steps>
  <Step title="Run hq login">
    It asks HQ for a one-time code, prints it, and opens the approval page in your browser.

    ```text
    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.3.2, macOS arm64)
    Waiting for approval (code expires in 10 min, Ctrl-C to cancel)...
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Back in the terminal">
    `hq` notices the approval within a few seconds:

    ```text
    Logged in as you@example.com · access renews automatically on this device
    Orgs: Acme (acme)
    Next:
      hq status                          see your teams and their hq-… names
      hq forward <port> --team <team>    reach a port on an AI Team Cloud Computer
      hq attach <session> --team <team>  join an HQ session in this terminal
    Or use the AI Workforce One HQ extension for VS Code.
    ```
  </Step>
</Steps>

<Callout title="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.
</Callout>

## Sign in without a browser [#sign-in-without-a-browser]

On a server, in a container or over a remote shell, run `hq login --no-browser`. `hq` prints the
sign-in page and the code instead of opening a browser. Open the page on any device where you are
signed in to HQ and type the code; the terminal finishes the login as usual:

```text
Go to https://hq.aiworkforceone.com/device in a browser and enter:

    BCDF-GHJK
```

Setting `HQ_NO_BROWSER=1` does the same for every `hq login`. `hq` also skips the browser on its
own where none can show: on Linux with neither `DISPLAY` nor `WAYLAND_DISPLAY` set, and when its
output is not a terminal (a pipe or a script).

## Where the login is kept [#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 [#check-who-is-signed-in]

```bash
hq status
```

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

## Sign in to another HQ address [#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://`.

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

## Sign out [#sign-out]

```bash
hq logout
```

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

## If it fails [#if-it-fails]

| Message                                              | What 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](/docs/cli/troubleshooting/).
