AI Workforce OneHQDocs

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

FlagDescription
--helpPrint the command list and exit. -h and hq help work too.
--versionPrint 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

VariableDescription
HQ_HOSTThe HQ address every command uses, overriding the one saved at hq login. Must be https.
HQ_HOMEWhere the CLI keeps its state, device key and fallback login. Default ~/.hq.
HQ_LOCAL_ECHOauto, always or off for hq attach. The --local-echo flag wins over it.
HQ_NO_BROWSERSet to 1 and hq login prints the sign-in link instead of opening a browser, like --no-browser.
HQ_KEYCHAINSet 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

FlagDescription
--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-browserPrint 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-browser

Exit codes

CodeMeaning
0Signed in.
1The 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 status

Examples

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

Exit codes

CodeMeaning
0Printed.
1Not 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

FlagDescription
--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-3f9a1c2e

Exit codes

CodeMeaning
0The AI Team Cloud Computer is running.
1No such team, remote access is off, or the Cloud Computer did not wake in time (3 minutes, 4 on the sizes from 80 GB).
2No 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

FlagDescription
--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-echo

Exit codes

CodeMeaning
0Detached with Ctrl-], or the session ended.
1No session matched (or more than one did), HQ could not be reached, or your access ended.
2No 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

FlagDescription
--team <t>Only list the sessions of this team (its hq-… name or its name).
--jsonPrint 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 --json

Exit codes

CodeMeaning
0Printed (a team whose list could not be read is named on stderr).
1Not 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

FlagDescription
--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.
--jsonPrint 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-3f9a1c2e

Exit codes

CodeMeaning
0HQ is starting the session, or it was already starting or running.
1No 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.
2No 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

FlagDescription
--yesDo 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.
--jsonPrint 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" --yes

Exit codes

CodeMeaning
0Stopped, or it was already stopped.
1No 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.
2No 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

FlagDescription
--yesDo 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.
--jsonPrint 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 7c21e0b4

Exit codes

CodeMeaning
0HQ is restarting the session.
1No 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.
2No 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

FlagDescription
--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-3f9a1c2e

Exit codes

CodeMeaning
0Stopped with Ctrl-C.
1No team lets you forward, the local port is taken, or the forward ended on the HQ side.
2The 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 logout

Examples

# Sign out and revoke this computer.
hq logout

Exit codes

CodeMeaning
0Signed out. If HQ could not be reached, the login is still removed from this computer and a warning is printed.