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_KEYCHAIN`	Set to `file` to store the login in `~/.hq/credentials.json` (readable only by you) instead of the system keychain.

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>]

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`.

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

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

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

hq status

Examples

# 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

Wake a sleeping team machine and wait until it is ready (about 15 seconds, up to 3 minutes).

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

Exit codes

Code	Meaning
`0`	The team machine is running.
`1`	No such team, remote access is off, or the machine did not wake within 3 minutes.
`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-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 forward

Make a port on the team machine 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 team machine 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

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

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

Was this page helpful?