# CLI reference

Every hq command, its flags, an example and its exit codes.



{/* Generated from cli/src/command-manifest.ts by `npm run gen:cli-docs`. Do not edit by hand. */}

This page is generated from the same command list `hq --help` prints, so the two always agree.
Wherever a command takes `<team>`, use the `hq-…` name from `hq status` or the team name.

## Global flags [#global-flags]

| Flag        | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| `--help`    | Print the command list and exit. `-h` and `hq help` work too. |
| `--version` | Print the CLI version and exit. `hq version` works too.       |

## Exit code 2 [#exit-code-2]

Every command exits `2` when it is missing a required argument (`hq` prints
`hq: missing arguments for "…". Run hq --help.`), and `hq` exits `2` for an unknown command or
when run with no command at all. The tables below list each command's other codes.

## Environment variables [#environment-variables]

| Variable        | Description                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `HQ_HOST`       | The HQ address every command uses, overriding the one saved at `hq login`. Must be https.                           |
| `HQ_HOME`       | Where the CLI keeps its state, device key and fallback login. Default `~/.hq`.                                      |
| `HQ_LOCAL_ECHO` | `auto`, `always` or `off` for `hq attach`. The `--local-echo` flag wins over it.                                    |
| `HQ_NO_BROWSER` | Set to `1` and `hq login` prints the sign-in link instead of opening a browser, like `--no-browser`.                |
| `HQ_KEYCHAIN`   | Set to `file` to store the login in `~/.hq/credentials.json` (readable only by you) instead of the system keychain. |

## hq login [#hq-login]

Sign this computer in with a one-time code you approve in HQ in your browser. The login is stored in the system keychain, or in `~/.hq/credentials.json` where there is none.

```bash
hq login [--host <url>] [--no-browser]
```

**Flags**

| Flag           | Description                                                                                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--host <url>` | The HQ address to sign in to. Defaults to `https://hq.aiworkforceone.com`, or to `HQ_HOST` when set. Only localhost may use plain `http`.                                                                     |
| `--no-browser` | Print the sign-in link instead of opening a browser. `hq` also skips the browser when `HQ_NO_BROWSER=1` is set, on Linux with neither `DISPLAY` nor `WAYLAND_DISPLAY`, and when its output is not a terminal. |

**Examples**

```bash
# Sign in to HQ. Your browser opens the approval page.
hq login

# Sign in to a specific HQ address.
hq login --host https://hq.aiworkforceone.com

# Sign in from a server or a remote shell: open the printed link on any device.
hq login --no-browser
```

**Exit codes**

| Code | Meaning                                                                            |
| ---- | ---------------------------------------------------------------------------------- |
| `0`  | Signed in.                                                                         |
| `1`  | The login was denied in the browser, the code expired, or HQ could not be reached. |

## hq status [#hq-status]

Show who is signed in and every team you can reach, with its `hq-…` name, whether its AI Team Cloud Computer is running, and what you may do there.

```bash
hq status
```

**Examples**

```bash
# List your teams and their hq-… names.
hq status
```

**Exit codes**

| Code | Meaning                                    |
| ---- | ------------------------------------------ |
| `0`  | Printed.                                   |
| `1`  | Not signed in, or HQ could not be reached. |

## hq up [#hq-up]

Wake a sleeping AI Team Cloud Computer and wait until it is ready (usually 15-30 seconds, 30-45 seconds on Boost Max, 120-180 seconds on the sizes from 80 GB). It waits up to 3 minutes, and up to 4 minutes on the sizes from 80 GB.

```bash
hq up <team> [--org <slug>]
```

**Flags**

| Flag           | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| `--org <slug>` | Only look in this organization, when you belong to more than one. |

**Examples**

```bash
# Wake the team with this hq-… name.
hq up hq-3f9a1c2e
```

**Exit codes**

| Code | Meaning                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------- |
| `0`  | The AI Team Cloud Computer is running.                                                                                 |
| `1`  | No such team, remote access is off, or the Cloud Computer did not wake in time (3 minutes, 4 on the sizes from 80 GB). |
| `2`  | No team named.                                                                                                         |

## hq attach [#hq-attach]

Join an HQ session in this terminal and follow it live. Only the session owner can type; everyone else watches. Press `Ctrl-]` to detach; the session keeps running.

```bash
hq attach <session> [--team <t>] [--local-echo[=auto|always|off]] [--org <slug>]
```

**Flags**

| Flag                               | Description                                                                                                                                                                            |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--team <t>`                       | Only look for the session in this team (its `hq-…` name or its name). Use it when the same session name exists in two teams.                                                           |
| `--local-echo[=auto\|always\|off]` | Draw what you type immediately instead of after the round trip. Bare `--local-echo` means `auto`. Wins over `HQ_LOCAL_ECHO`; off when neither is set. Your organization must allow it. |
| `--org <slug>`                     | Only look in this organization, when you belong to more than one.                                                                                                                      |

**Examples**

```bash
# Attach by the first characters of the session id.
hq attach 7c21e0b4

# Attach by session name in one team, with local echo.
hq attach "fix login bug" --team hq-3f9a1c2e --local-echo
```

**Exit codes**

| Code | Meaning                                                                                   |
| ---- | ----------------------------------------------------------------------------------------- |
| `0`  | Detached with `Ctrl-]`, or the session ended.                                             |
| `1`  | No session matched (or more than one did), HQ could not be reached, or your access ended. |
| `2`  | No session named, or `--local-echo` was not auto, always or off.                          |

## hq sessions [#hq-sessions]

List the sessions in your teams: the first characters of each id, its name, its team, whether it is running, who owns it, and whether you may start, stop and restart it. View-only sessions are listed too.

```bash
hq sessions [--team <t>] [--json] [--org <slug>]
```

**Flags**

| Flag           | Description                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `--team <t>`   | Only list the sessions of this team (its `hq-…` name or its name).                                          |
| `--json`       | Print the result as one JSON document on stdout. Refusals are still plain text on stderr, with exit code 1. |
| `--org <slug>` | Only look in this organization, when you belong to more than one.                                           |

**Examples**

```bash
# List the sessions in all your teams.
hq sessions

# List one team as JSON, for a script.
hq sessions --team hq-3f9a1c2e --json
```

**Exit codes**

| Code | Meaning                                                           |
| ---- | ----------------------------------------------------------------- |
| `0`  | Printed (a team whose list could not be read is named on stderr). |
| `1`  | Not signed in, or HQ could not be reached.                        |

## hq start [#hq-start]

Start a stopped session, by the first characters of its id or its name. A sleeping AI Team Cloud Computer wakes for it, as when you press Start in HQ. Only the session owner or a team owner can start it.

```bash
hq start <session> [--team <t>] [--json] [--org <slug>]
```

**Flags**

| Flag           | Description                                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--team <t>`   | Only look for the session in this team (its `hq-…` name or its name). Use it when the same session name exists in two teams. |
| `--json`       | Print the result as one JSON document on stdout. Refusals are still plain text on stderr, with exit code 1.                  |
| `--org <slug>` | Only look in this organization, when you belong to more than one.                                                            |

**Examples**

```bash
# Start a session by the first characters of its id.
hq start 7c21e0b4

# Start a session by name in one team.
hq start "fix login bug" --team hq-3f9a1c2e
```

**Exit codes**

| Code | Meaning                                                                                                                                      |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | HQ is starting the session, or it was already starting or running.                                                                           |
| `1`  | No session matched (or more than one did), you may not operate it, the team has no free session slot, or HQ refused or could not be reached. |
| `2`  | No session named.                                                                                                                            |

## hq stop [#hq-stop]

Stop a running session. If Claude or Codex is answering in it right now, `hq` asks first; in a script, pass `--yes`. Only the session owner or a team owner can stop it.

```bash
hq stop <session> [--yes] [--team <t>] [--json] [--org <slug>]
```

**Flags**

| Flag           | Description                                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--yes`        | Do not ask before interrupting a session that is answering. Without it, and without a terminal to ask at, `hq` refuses.      |
| `--team <t>`   | Only look for the session in this team (its `hq-…` name or its name). Use it when the same session name exists in two teams. |
| `--json`       | Print the result as one JSON document on stdout. Refusals are still plain text on stderr, with exit code 1.                  |
| `--org <slug>` | Only look in this organization, when you belong to more than one.                                                            |

**Examples**

```bash
# Stop a session.
hq stop 7c21e0b4

# Stop it without asking, even while it is answering.
hq stop "fix login bug" --yes
```

**Exit codes**

| Code | Meaning                                                                                                                                                                                    |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`  | Stopped, or it was already stopped.                                                                                                                                                        |
| `1`  | No session matched (or more than one did), you may not operate it, you answered no, it is answering and there is no terminal to ask (pass `--yes`), or HQ refused or could not be reached. |
| `2`  | No session named.                                                                                                                                                                          |

## hq restart [#hq-restart]

Stop a session and start it again, resuming its conversation. Like `hq stop`, it asks first while the session is answering. Only the session owner or a team owner can restart it.

```bash
hq restart <session> [--yes] [--team <t>] [--json] [--org <slug>]
```

**Flags**

| Flag           | Description                                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--yes`        | Do not ask before interrupting a session that is answering. Without it, and without a terminal to ask at, `hq` refuses.      |
| `--team <t>`   | Only look for the session in this team (its `hq-…` name or its name). Use it when the same session name exists in two teams. |
| `--json`       | Print the result as one JSON document on stdout. Refusals are still plain text on stderr, with exit code 1.                  |
| `--org <slug>` | Only look in this organization, when you belong to more than one.                                                            |

**Examples**

```bash
# Restart a session.
hq restart 7c21e0b4
```

**Exit codes**

| Code | Meaning                                                                                                                                                                                    |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`  | HQ is restarting the session.                                                                                                                                                              |
| `1`  | No session matched (or more than one did), you may not operate it, you answered no, it is answering and there is no terminal to ask (pass `--yes`), or HQ refused or could not be reached. |
| `2`  | No session named.                                                                                                                                                                          |

## hq forward [#hq-forward]

Make a port on the AI Team Cloud Computer reachable at `http://localhost:<port>` on this computer, until you press `Ctrl-C`.

```bash
hq forward <port> [--local <port>] [--team <t>] [--org <slug>]
```

**Flags**

| Flag             | Description                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| `--local <port>` | The port on this computer. Defaults to the same number as the team port. It listens on 127.0.0.1 only. |
| `--team <t>`     | Which team to forward from. Optional when exactly one of your teams lets you forward ports.            |
| `--org <slug>`   | Only look in this organization, when you belong to more than one.                                      |

**Examples**

```bash
# Reach port 3000 on the AI Team Cloud Computer at localhost:3000.
hq forward 3000

# Reach port 5173 of one team at localhost:8080.
hq forward 5173 --local 8080 --team hq-3f9a1c2e
```

**Exit codes**

| Code | Meaning                                                                                  |
| ---- | ---------------------------------------------------------------------------------------- |
| `0`  | Stopped with `Ctrl-C`.                                                                   |
| `1`  | No team lets you forward, the local port is taken, or the forward ended on the HQ side.  |
| `2`  | The team port is missing or not a number from 1024 to 65535, or `--local` is not a port. |

## hq logout [#hq-logout]

Revoke this computer's access on HQ (in every organization) and remove the stored login.

```bash
hq logout
```

**Examples**

```bash
# Sign out and revoke this computer.
hq logout
```

**Exit codes**

| Code | Meaning                                                                                                         |
| ---- | --------------------------------------------------------------------------------------------------------------- |
| `0`  | Signed out. If HQ could not be reached, the login is still removed from this computer and a warning is printed. |
