Start and stop sessions
hq sessions lists the sessions in your teams; hq start, hq stop and hq restart run them from your terminal, with the same rules as HQ.
Only the session owner or a team owner can start, stop or restart a session, exactly as in HQ. Everyone else sees it in the list as view only.
List your sessions
hq sessions lists the sessions of every team you can reach: the first characters of the id, the
name, the team, whether it is running, who owns it (you for your own), and whether you may operate
it.
3 sessions in 2 teams
7c21e0b4 fix login bug Backend team running you can operate
1a2b3c4d nightly Backend team stopped Ana view only
9f9f9f9f landing page Website stopped you can operateAdd --team <t> to list one team, by its hq-… name or its name. If one team's list cannot be
read, hq names it (hq: could not list the sessions of team "…".) and still prints the others.
Start, stop and restart
Name a session by the first characters of its id or by its exact name, the same way as
hq attach. Add --team <t> when the same name exists in two teams. The
rawName a script read from --json works as a name too (see Use it from a script).
# start a stopped session
hq start 9f9f9f9f
# stop a session
hq stop "fix login bug"
# stop and start it again, resuming its conversation
hq restart 7c21e0b4-
Start wakes a sleeping AI Team Cloud Computer for the session, and starts one that is off, as pressing Start in HQ does.
hqsays so first, for examplehq: team "…" is sleeping. Starting the session wakes it.It returns once HQ has accepted the start. Follow the session withhq attach. -
Stop and Restart ask first when Claude or Codex is answering in the session right now:
Claude is answering in "fix login bug" right now. Stop it anyway? [y/N]Anything but
ykeeps it running. In a script, or anywhere without a terminal to ask at,hqrefuses instead and tells you to pass--yes.
A session that is already running (for hq start) or already stopped (for hq stop) is not an
error: hq says so and exits 0. A session HQ is still starting says "is already starting", with
the hq attach command to follow it: hq only says running once HQ lists the session as running.
Every start, stop and restart is recorded in your organization's Audit log in HQ as coming from the HQ CLI, for example "Stopped a session fix login bug in Backend team from the HQ CLI on Jean's MacBook." The computer's name shows to people who can manage remote access; everyone else who can read the Audit log sees a short device id instead, such as "on device 3f2a9c1b".
When hq says no
| What you see | Why |
|---|---|
| Only the session owner or a team owner can do this. | You can watch this session but not operate it. The same sentence HQ shows. |
hq: no session "…" you can see. Run hq sessions to list them. | No session you can see has that name or id. |
| Team "…" is running as many sessions as it can (…). Stop one of its sessions first, or give the team more room in HQ. | The team is at its session limit. |
| This AI Team's Cloud Computer is busy right now, so another session could not start. Stop a session you no longer need, or move the team to a bigger size, then try again. | The team has a free slot, but its Cloud Computer is too busy (memory at 80% or more, or the processor at full capacity). |
| Team "…" is paused. An owner can resume it in HQ. | The team is paused. |
| This organization's plan is not active, so its sessions cannot be started or stopped. An owner can fix billing in HQ. | The plan needs attention. |
| Too many requests. Try again in 34 seconds. | More than 30 starts and restarts in a minute, or a team woken too often (6 times in 10 minutes). hq says how long HQ asked you to wait. Stopping is never limited. |
| HQ refused this request because it was not signed by this computer. That is a bug in this app, not an expired login, so signing in again will not help. Update the app and try again. | Your login is fine, but this copy of hq sent a change without its device signature. Update hq. If it keeps happening, tell us. |
Use it from a script
Add --json to any of the four commands to get one JSON document on stdout. Refusals stay plain
text on stderr, with exit code 1.
# the ids of the sessions you may operate in one team
hq sessions --team hq-3f9a1c2e --json | jq -r '.[] | select(.canOperate) | .id'
# stop without asking, and read the result
hq stop 7c21e0b4 --yes --jsonEach listed session has id, name, rawName, team (id, alias, name, org), state
(running, idle, starting or stopped; starting while HQ is still starting it, which
can still fail), owner, ownerIsMe, canOperate, canType, midTurn and
engine. A start, stop or restart prints id, name, rawName, team, action, result
(started, stopped, restarted, already_starting, already_running or already_stopped)
and status.
name is the name as hq displays it: any control character (an escape sequence, a line break)
is replaced with a space so it cannot change your terminal, and any bidirectional text control
(such as U+202E, which would show the name reversed) is removed. The hq sessions table shows
the same cleaned names. rawName is the exact name HQ holds.
In the JSON, every control character in it is written as a \uXXXX escape, so the line hq
prints is still safe to show. A JSON parser gives your script the exact value; print name, not
rawName, to a terminal (jq -r .rawName would write those characters out as they are).
hq start, hq stop and hq restart match either one.
midTurn comes from the AI Team Cloud Computer itself, which reports whether its agent is busy. It
is about the whole Cloud Computer, so while one session is answering, every running session on that
team reads true.
Every flag and exit code is in the CLI reference.