CLI reference
Every hq command, its flags, an example and its exit codes.
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
| 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
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
| 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
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.
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
# 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-browserExit 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
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.
hq statusExamples
# List your teams and their hq-… names.
hq statusExit codes
| Code | Meaning |
|---|---|
0 | Printed. |
1 | Not signed in, or HQ could not be reached. |
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.
hq up <team> [--org <slug>]Flags
| Flag | Description |
|---|---|
--org <slug> | Only look in this organization, when you belong to more than one. |
Examples
# Wake the team with this hq-… name.
hq up hq-3f9a1c2eExit 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
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.
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
# 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-echoExit 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
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.
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
# List the sessions in all your teams.
hq sessions
# List one team as JSON, for a script.
hq sessions --team hq-3f9a1c2e --jsonExit 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
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.
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
# 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-3f9a1c2eExit 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
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.
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
# Stop a session.
hq stop 7c21e0b4
# Stop it without asking, even while it is answering.
hq stop "fix login bug" --yesExit 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
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.
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
# Restart a session.
hq restart 7c21e0b4Exit 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
Make a port on the AI Team Cloud Computer reachable at http://localhost:<port> on this computer, until you press Ctrl-C.
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
# 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-3f9a1c2eExit 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
Revoke this computer's access on HQ (in every organization) and remove the stored login.
hq logoutExamples
# Sign out and revoke this computer.
hq logoutExit 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. |