Attach to a session
hq attach joins an HQ session in this terminal, streaming its output live. Only the session owner can type; everyone else watches.
The person who started a session is the only one who can type in it. Everyone else who attaches watches it live, view only. To work yourself, start your own session in HQ.
How it works
- Find the session
Open the team in HQ: its session list shows each session's name. You can attach by that name or by the first characters of the session id.
- Attach
Run
hq attach <session>. Add--team <t>when the same name exists in more than one team. - Detach when you're done
Press
Ctrl-]. The session keeps running; you can attach again any time.
# attach to a session by the start of its id
hq attach 7c21e0b4
# show what you type instantly, before the round trip confirms it
hq attach 7c21e0b4 --local-echo# attach to a session by the start of its id
hq attach 7c21e0b4
# show what you type instantly, before the round trip confirms it
hq attach 7c21e0b4 --local-echoWhen it connects, hq tells you whose session it is and whether you can type:
Attached to "fix login bug" (Dana) · you can type · Ctrl-] to detachLocal echo
On a slow connection, --local-echo draws your keystrokes the moment you press them, instead of
after the round trip to the team machine. It only applies when you can type and your terminal is a
real terminal.
| Setting | Behavior |
|---|---|
--local-echo or --local-echo=auto | Echo locally only while the round trip is slower than 60 ms. |
--local-echo=always | Echo locally at any speed. |
--local-echo=off | Never. This is the default. |
Set HQ_LOCAL_ECHO=auto in your shell profile to make it your default; the flag wins over it.
Your organization has to allow local echo; when it does not, hq says so once and attaches
without it.
When the team machine is sleeping
Attaching usually wakes it, and hq prints progress while it starts: about 15 seconds for a
wake, about a minute when it has to start fresh, and it gives up after 3 minutes. If you see
Press any key to continue., the machine was not woken for you; the next key you press wakes it.
If the connection drops, hq reconnects on its own, up to 8 times in a row, and prints
hq: connection lost, reconnecting... while it does.