Daily use
Attaching
Run clawee with no arguments to open the session picker and attach. Name a box to go straight to it:
claweeOpen the session picker and attach.clawee [[<user>@]<box>]Attach on that box, optionally as that user — a box name, a fingerprint prefix, or local (see gateways).clawee [<user>@]<box> --ssh <host>Attach over ssh at one of that box's hosts.clawee ssh <host>Attach over ssh to a host added with clawee ssh add.Flags tune the bare invocation:
--burrowee <addr>Reach the box over burrowee via this relay address (default: the pinned relay).-i <key>Private key file to authenticate with (default: ssh-agent, then ~/.clawee/id_ed25519).--reconnect-timeout <deadline>Per-attempt reconnect deadline (default: config, then 5s).-s <sid>Attach the remote pty session id directly.--socket <path>Transport daemon socket path (default: $BURROWEE_TRANSPORT_SOCK, then config).--ssh <host>Reach the box over ssh at this host — needs a box: clawee <box> --ssh <host>.--transport <mode>Transport mode: auto | ws | quic (default auto; empty = daemon default).--user <user>Gateway OS user to claim for this run.--viewOpen the session read-only — a viewer: live screen and transcript; t takes the writer role (see viewers & the writer role).
There is no -r/resume flag on the released binary.
While you are attached, the terminal tab title is ● <name>. When the attached session
is asking for you — its attention is question, permission or
waiting — the title reads ● <icon> <kind> · <name> — ● ❓ question,
● ❗ permission or ● ⏳ waiting (the icon follows the glyph table, so text mode
gives ! permission for the second) — and any other attention shows the plain name again. The title is never changed
before it was saved or after clawee has restored it on exit.
Reference
Views & keys
Once attached, keystrokes pass through to the remote shell except:
Ctrl+]Open the command composer (type a /command or text; Enter sends).Ctrl+\Lock the screen (unlock with the lock passphrase).F5 · Ctrl+[Redraw the remote screen in place — on claweed ≥ v0.1.53 this repaints straight from the session holder, on the alt screen and the main screen alike; an older holder falls back to the previous app-nudge. It never touches the connection, so it is cheap to lean on. (Ctrl+[ needs the kitty keyboard protocol, e.g. Ghostty.)Shift+F5 · Ctrl+Opt+[Redraw the hard way, by reattaching — for when the redraw above leaves something behind. It drops the stream and re-attaches the same session with the full replay, so it costs a reconnect; /reconnect does the same from the composer. (Ctrl+Opt+[ needs the kitty keyboard protocol; Shift+F5 works in any terminal.)clawee has one more full-screen view behind most of these keys. Each takes over the terminal, carries its key bar in the header, and leaves with q:
session pickerBare clawee — one list: this device's sessions on top, remote-only ones below. Keys below.pairing formThe picker on an unpaired device — see pairing.box chooserg, or clawee gw — every box and user, over burrowee or ssh — see gateways.relay list/relays, clawee relays, or l in the picker (a burrowee route) — see relays.devices viewv in the picker, on a burrowee route once paired — see devices.connections overlayc in the picker — who is on the selected session — see below.watch vieww in the picker, or clawee --view — the session read-only — see viewers.lock screenCtrl+\, an idle timeout, or clawee's startup — see locking.history pager/history and /commands — see slash commands.version panel/version — clawee + claweed builds; Esc goes back.
The picker's header also carries an identity line, 🌐 <user>@<gateway> via <route>
(💻 on this machine's own box) — which account you're connected as, and how. It renders on
every setup, including a single gateway, followed by · switch (g); the
/switch picker leaves the hint off, because g does nothing there.
In the session picker (not while attached) — these never reach the remote shell:
Enter · nAttach the selected session (a remote-only row gets this device's record as it attaches) · start a new one — + new session at the top does the same.aAuthenticate this device — only offered while this (gateway, user) isn't trusted yet. See below.s · tStop the session — it stays listed, under stopped sessions · restart it.pPurge it — the gateway, this device and the list: close it if it is live, purge it from the gateway, and forget this device's record. On a detached row (its remote session already gone) it removes just the record; on a remote-only row, just the gateway's session.iPin / unpin the session — pinned sessions stay at the top.r · wReload the list now · watch the session read-only.cOpen the connections overlay for the selected session — see below.lSwitch the gateway's relay right there — a compact list, Enter switches, q backs out. On a burrowee route only.vOpen the devices view (approve / revoke device keys) — on a burrowee route, once this device is paired.gOpen the box picker — boxes, their users and hosts (see gateways).q · Ctrl+CQuit clawee.
The bar reads new (n) · stop (s) · purge (p) · reload (r) · quit (q). Under the list an
idle tip reads pin (i) · restart (t) · watch (w), then relays (l) on a burrowee
route and devices (v) once paired. Enter and c work without being
listed. p asks first, naming the session. x close is gone — p does
what it did. There is no rename here — /name in the composer renames — and no
detach. In the /switch picker the row keys refuse on the session you're attached to:
/detach first.
a shows up only once this (gateway, user) isn't trusted: the picker opens on a
⚿ authenticate this device row above + new session, with a detail line
like not paired — <gateway> / <user>, and the key bar leads with auth (a) — auth (a) · new (n) · stop (s) · purge (p) · reload (r) · quit (q). Enter on that row does the same thing as
a.
A failed n new-session or attach keeps you in the picker rather than exiting: a stray
new session failed: … — ⏎ retries or attach failed: … — pick again to retry
notice appears and Enter tries again. A create refused for want of trust also runs the
auth flow in place, then retries the create; backing out reopens the picker with the ordinary
new session failed: … — ⏎ retries notice. An attach refused the same way backs out
to not authenticated for this gateway — press a to authenticate instead.
The picker is one list (clawee v0.3.13 — it used to be a Local and a Remote tab), in sections: current session (the one you're attached to, or just left) · available sessions (idle, nobody attached) · connected sessions (another client holds them) · stopped sessions (closed, exited or interrupted — and any record whose remote session is gone, shown as detached) · remote sessions (on the gateway, with no record on this device; painted in their own colour while live). Every record this device keeps has its row, so nothing the old Local tab showed is lost.
After a confirmed s, p or t, clawee swallows
the very next Enter and the footer reads ⏎ ignored — move the cursor first.
That's the reflex Enter that used to tag along right after a fast y confirm,
landing on the freshly repainted list and attaching or creating a session by accident. Any other
key clears the guard immediately, and the very next Enter after that acts normally.
A session's state: connected (someone's attached) ·
idle (alive, nobody attached) · interrupted (the holder is gone — a reboot or
crash — but attaching restores it: the full retained scrollback replays, with a
── session re-established · was running: <cmd> ── marker when the daemon
knows the foreground command (bare ── session re-established ── when it
doesn't; a claude session gets a claude --continue hint)) ·
exited · closed.
green = connected · blue = idle · gray = detached · interrupted = attach to restore · live = recency · size = total output · last col = who holds it
Each session takes two rows. Row 1 carries the session's attention —
❓ question · ❗ permission · ⏳ waiting · ✅ done ·
💤 idle · 🔄 working · ❌ error — and the kind of client that
opened it: 👤 TUI · 🤖 agent · 📱 app. Row 2 carries the
kind of the connection on it now, left blank when that is the opener's kind, and a mark:
👀 watched (another device is viewing, or a demoted writer is still attached) or
🔀 hand-off (a take is pending; it wins over 👀). +N after
the route counts the viewers. 📌 marks a pinned session, 👻 one with no
record on this device, and 🔼 after the PTY a session whose holder is older than its daemon.
Text mode — CLAWEE_ICONS=text, a locale without UTF-8, or a TERM of
dumb, linux or the vt100 family — swaps every icon for one ASCII
cell: ? ! . v z >
x for the attention kinds above, T / A / M for
TUI / agent / app, w watched, h hand-off, * pinned,
# no record, ^ holder older. CLAWEE_ICONS=emoji forces the icons.
c opens the connections overlay for the selected session, titled
connections · <name> · <sid>, bar take (t) · cancel (esc) · back (q).
One row per connection: kind icon, device, then route · role · stream · since, and
(this client) on your own. Roles are writer, viewer and
read-only (a demoted writer still attached); streams are pty,
input, sync, screen and follow. While a take is
pending, a last line reads pending take: <device> (<kind>) · <age> · writer idle in Ns.
The overlay refreshes every second.
tTake the writer role: asks take the write role from <device> (<kind>)? (y/n), then shows waiting for <device> to finish… (Esc cancels) · idle in Ns until it arrives — you are writing.EscCancel your pending take (take cancelled); with none pending, close the overlay.q · Ctrl+CClose the overlay — closing cancels your pending take.
Against a daemon too old to list connections, the overlay shows writer: and
viewers: lines and says daemon too old for details.
Reference
Viewers & the writer role
A session has one writer — the one client whose keys reach the shell — and any number of
viewers. w in the picker, or clawee --view, opens the watch view:
the live screen and the transcript, read-only. Its keys:
h j k l · gPan a screen larger than your terminal · back to the top-left corner.cShow or hide the session's chat pane./A viewer command: /chat [--paste] <text> (bare /chat opens the pane), /history, /take, /quit.tTake the writer role.q · Ctrl+CLeave the watch view.
Taking the role. Between the owner-role devices of one tenant a take needs no approval and
has no countdown. It completes when the writer goes idle — no keystroke, paste or resize, or
clawee sessions send, for 5 s; output and attention do not count — when it gives the
role up (answers y), or when it disconnects. An idle writer hands over at once. The writer's
give-up prompt below only offers an earlier hand-over: n, or no answer, keeps the writer
typing until it goes idle. There are never two writers.
The writer who loses the role stays attached, read-only: the screen keeps streaming, only its
input is withheld. clawee says you are writing or
read-only — <device> (<kind>) is writing. A key that would reach the shell, or
t, asks take the write role from <device> (<kind>)? (y/n) — and that
key is not sent. While the take waits: waiting for <device> to finish… (Esc cancels) · idle in Ns.
The writer is asked <device> (<kind>) wants to write — give it up? (y/n), with no
countdown; no, or no answer, keeps it writing until it goes idle. /release in the composer
gives the role up without detaching.
A human and an agent are two writers, even on one machine with one key. An agent that has not
taken the session cannot type over a human: clawee sessions send exits 3 with
read-only, taken by <device>. On a free session it becomes the writer.
clawee sessions take <addr> waits while the writer is active, printing
waiting for <device> (<kind>) to finish… to stderr; Ctrl+C or
SIGTERM cancels it. clawee sessions release <addr> gives the role up.
A device enrolled as a viewer (devices) may watch, follow, snapshot
and chat, never write: the watch view answers t with
this device is viewer-only: it cannot take the session, and the session verbs with
read-only device: this key is enrolled viewer-only.
Reference
Headless sessions
Every session also runs without a terminal, for scripts and agent harnesses. An address is
[user@]gateway[#relay]/session — or /session for the pinned gateway — and a
session is its exact name, else a unique sid prefix. Each verb reaches the box the way attach does:
local, then ssh, then burrowee; --ssh <host> or --burrowee forces one.
clawee sessions [--json] [--watch]List the daemon's sessions, or stream their events.sessions newCreate a session headlessly (120x40 by default) and print its sid. --name, --cwd, --shell, --preset default|phone, --cols / --rows; --aqua runs it in the desktop login session of the gateway user (macOS, that user logged in).sessions read · attach · screenPrint the last lines · follow the output · print the current screen (--format text for agents, --follow to keep printing).sessions send · uploadType text and named keys into a session (exit 3 = read-only) · copy a file or folder to its box.sessions take · releaseTake the writer role · give it up — see above.sessions status · signalPrint a session's attention · set it.sessions chatSend to the session's chat room, or --history to read it.sessions purgeClose (if live), purge and forget — the picker's p, no confirm.sessions dropsOne verdict per connection drop, from this client's and the burrowee daemon's logs (see relays).clawee exec <box> -- <argv…>Run one command on a box and exit with its status — no terminal, no session.clawee agentWatch every session that wants attention and print it (or --exec a command for it), one at a time.
A session's attention comes from the program inside it first: a program that speaks the
OSC 7501 program-status escape reports its own state — working, done, blocked on a question or a
permission, error — and progress. A hook can set it with sessions signal; only a program
that says nothing falls back to clawee's own reading of a quiet prompt. sessions status
prints it with its source.
Every flag is in the clawee CLI reference.
Reference
Locking
Set a passphrase and clawee can cover the screen — on demand, after an idle period, or before
it will open a session at all. The lock screen shows the session, gateway, relay and versions,
but no terminal content — and a host row with the box's load, for example
thermal … · cpu N% · mem 14.4/32gb 45%, each part only when the daemon reports it
(not reported when it reports none). mem is used of total and its percent, coloured
as a warning from 50% and as hot from 85%; the parts are joined by · and wrap to the
terminal, at most 3 lines. Below it a disk row, one line per disk in four left-aligned
columns — name, used, total, percent — each padded to its widest value, for example:
host thermal … · cpu 12% · mem 14.4/32gb 45%
disk Macintosh HD 82.1gb 228gb 36%
Data 1.2tb 2.0tb 60%
The name is the disk's own (the root volume shows
its volume name, a Linux disk its label, ZFS its pool); only an unnamed disk shows its mount, and a name
too wide for the terminal is shortened in the middle. Each line is coloured by its own percent, as a
warning from 80% and as hot from 90%; sizes read 512mb, 82.1gb,
228gb, 2.0tb. claweed lists real local disks only — on macOS local APFS, HFS,
exFAT, FAT and NTFS volumes, never simulator runtimes, network shares, FUSE or OrbStack mounts; on Linux
non-loop block devices (FUSE-backed USB disks included) and ZFS by pool — read-only ones included; bind
mounts and btrfs subvolumes show once, APFS volumes once per container. Mounts under another account's
home and /media/<user> are hidden from other accounts. At most 8 are listed, the largest
kept, and the rest count in a closing +N more. Both rows are on the lock screen and in
/version. An older claweed sends no list, and the disk row is one line without a
name:
disk 120gb 500gb 24%
clawee lock-passphraseSet the passphrase (masked entry). This is what turns the startup gate on.Ctrl+\ · /lockLock now — from the session, or from the composer./settingsSet or clear the passphrase from inside a session — the settings window's lock section.The lock screen tells you to type the passphrase and press Enter. It accepts a little more than that:
EnterTry the passphrase.BackspaceDelete one character.Ctrl+UReveal — toggle masking, to check what you typed.Ctrl+BackspaceClear the whole entry.Arrows, function keys and stray mouse clicks are swallowed rather than typed into the passphrase.
Unlocking always lands you back in passthrough — a composer that was open before the
lock is closed, not silently reopened. The screen you had before locking is preserved as-is; a
quiet unlock just repaints from the session holder. The one exception: if the connection dropped
and reconnected while locked, the buffered replay is discarded rather than risk showing
stale output, and a single hint appears once — reconnected while locked — the view may be
stale; ctrl+[ to refresh. A lock that is still waiting for the link says
disconnected — reconnects after unlock.
clawee asks for it before
opening a session — the same screen, before any network. Ten tries are free; from the tenth,
each further attempt waits 5 minutes, counted down on screen and remembered across restarts.
Ctrl+C gives up (the in-session lock can't be dismissed that way — it's
guarding a live session). The maintenance commands — status, doctor,
relays, devices, update — stay reachable without the
passphrase, so a forgotten one never leaves you unable to see why something's broken.
Reference
Composer editing
Keys inside the command composer (opened with Ctrl+]):
Enter · Shift+EnterSend the line · insert a newline (multi-line input; needs kitty-keyboard, e.g. Ghostty).PasteMulti-line pastes stay in the box; a pasted file path uploads the file; very large text is uploaded as a file too.← / →Move the cursor one character.Home/End · Ctrl+A/EJump to the current line start / end.Ctrl+Home/EndJump to the buffer start / end (on a Mac laptop: Fn+Ctrl+←/→).↑ / ↓Recall command history (older / newer).Backspace / DelDelete before / after the cursor.Ctrl+K / Ctrl+UKill to line end / to line start.Ctrl+BackspaceKill to line start (same as Ctrl+U).Ctrl+L · Ctrl+CKill the whole line · clear the box (stays open).TabComplete the /command.Esc · Ctrl+]Close the composer.Ctrl+\Lock the screen.
While clawee is connecting or reconnecting, the composer box stays up: Ctrl+C
clears the line and the hint says ctrl+c again to quit — a second
Ctrl+C within a second quits clawee. Under the reconnect box,
Ctrl+] or Esc closes a composer you opened and keeps its draft; the box
keeps its own keys.
Reference
Slash commands
Inside the composer (Ctrl+]):
/uploadSend a file or directory — /upload <path> (also: paste a path or drop a file). Directories go as tar.gz; uploads land in a dated uploads/<date>/… dir on claweed ≥ v0.1.30./downloadFetch a remote file or dir to your machine — /download <path>./nameSet the session's display name — /name <name> renames the remote pty and this device's record./relaysOpen the relay list — priority, skip, pin, probe — and switch the live session (see relays)./settingsThe settings window: uploads · lock + passphrase · connection · relays — or /settings <key> <value>./historyPage this session's scrollback, reflowed to this terminal — ↑↓ or j/k a line, Space/f and b a page, g/G top / bottom, q quits. The pager prints no key bar./commandsPage the commands run in the remote pty (alias /cmds), with the same keys./clearDrop this session's scrollback and history, here and on the host (alias /cls; Ctrl+Alt+K anywhere)./chatThe session's chat room — /chat <text> sends, /chat --paste <text> marks it pasteable, bare /chat opens the pane./releaseGive the writer role up without detaching — the session becomes free (see the writer role)./versionShow the clawee + claweed build versions and names (Esc goes back)./restartRestart the attached session in place./reconnectForce a reconnect now./refreshRepaint the remote screen now (alias /redraw)./detachDrop back to the session picker (the remote session keeps running)./switchJump straight to another session on this gateway — opens the session picker over the live session, ⏎ switches, Esc keeps the one you are in. No detach first, and nothing is released unless you actually pick a different session./lockLock the screen now — /lock [<passphrase>]./quitExit clawee (alias /q).
Stuck? clawee doctor diagnoses the chain, and clawee status shows
exactly where a connection stops.
Reference
CLI reference
Verbatim help pages for these commands, generated by clawee docs from the binary's own help renderer. The other sessions verbs, exec, agent and transport are in the full clawee CLI reference.
clawee
clawee — the Clawee terminal client.
Usage:
clawee [[<user>@]<box>] [flags] attach a session (optionally naming the box, and its user)
clawee [<user>@]<box> --ssh <host> attach over ssh at one of that box's hosts
clawee ssh <host> [flags] attach a session over ssh to a host added with 'clawee ssh add'
clawee <command> [flags]
Commands:
status alias of doctor (read-only) — probe the chain
and report
sessions list the daemon's pty sessions (--watch
streams events, --json prints data)
[--json] print the sessions as a JSON array (one
object per session) instead of the table
[--watch] stream session events until the daemon closes
the stream
new create a session headlessly (120x40 by
default, no terminal probe) and print its sid
[<addr-prefix>]
[--aqua] run the session in the desktop login session
of the gateway user (needs that user logged
in)
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--cols <N>] pty width in N columns (wins over --preset)
[--cwd <dir>] start the shell in this dir on the gateway
[--json] print {sid,name,gateway,user[,aqua]} instead
of the bare sid
[--name <name>] the session's name — refused when the gateway
already has one
[--preset <preset>] geometry preset: default (120x40) or phone
(80x30)
[--rows <N>] pty height in N rows (wins over --preset)
[--shell <path>] run this path instead of the gateway user's
login shell
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
read print the last N lines of a session's output
and exit
<addr>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[-n <N>] lines to print: N, or all (all = what the
gateway's ring retains, 4 MiB by default —
not the whole transcript)
[--raw] print ring bytes with escape codes intact
(text mode drops in-place TUI redraws; use
--raw for a TUI). On a LIVE session this is a
real attach: it takes the session over like
an interactive client and resizes it to
200x50. A closed session replays read-only;
exited and interrupted are refused, because
reading one would fork a fresh shell
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
attach follow a session's output — headless,
plaintext, stdout only
<addr>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--handle <name>] socket basename (name) for this attach's
handle; default a short hash of the
gateway+sid — for a second attach on one
session; a long name can still push the
socket path over the sun_path limit and is
refused; not with --raw
[-n <N>] backlog lines before following: N, or all
(what the gateway retains); not with --raw
[--raw] stream ring bytes with escape codes intact
(text mode drops in-place TUI redraws; a real
attach: takes the session over like an
interactive client)
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
send type text and/or named keys into a session
(no attach; exit 3 = read-only, another
device holds it)
<addr> [text ...]
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--enter] append a carriage return last, after --key
(and after --stdin, when given)
[--key <k[,k...]>] named keys to send after the text (or after
--stdin, when given), comma-separated
k[,k...], from enter tab esc up down left
right ctrl-c ctrl-d
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
[--stdin] send stdin bytes verbatim instead of
positional text (cannot combine with text
arguments); --enter/--key still apply,
appended after the stdin bytes
upload copy a file or folder to the session's box
and print its absolute remote path
<addr> <path>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--json] print one JSON object {path,size,sid,gateway}
instead of the bare path
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
screen print the session's current screen (ansi
repaint bytes, or --format text) without
attaching
<addr>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--follow] keep printing a snapshot whenever the screen
changes (text mode separates snapshots with a
form feed line) until the session ends or
Ctrl-C
[--format <format>] snapshot format: ansi (the styled repaint
bytes, default) or text (bare rows, for
agents)
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
status print the session's attention (kind, source,
app, progress, text, since) without attaching
<addr>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--json] print {kind, source, app, progress, text,
since, state, opened_kind} as one JSON object
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
take take the session's writer role (waits while
the writer is active; Ctrl-C cancels)
<addr>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
release give the writer role up without detaching
(the session becomes free)
<addr>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
signal set the session's attention state
(question|permission|idle|done|waiting|working|error|none)
<addr> <kind> [text ...]
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
chat send a chat message to the session's room, or
--history to read the log
<addr> [text ...]
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--from <N>] with --history: print messages after seq N
[--history] print the chat log instead of sending (one
line per message: seq, time, device, [paste],
text)
[--max <N>] with --history: at most N messages (0 = the
gateway's default page)
[--paste] mark the message as pasteable: the writer's
client offers a one-key paste of it into the
session
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
purge close (if live), purge and forget the session
— same effect as the picker's p, no confirm
<addr>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--json] print {sid} instead of a plain "purged <sid>"
line
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
drops merge this client's and the burrowee daemon's
connection logs: one verdict per drop episode
[--json] print the merged events of both logs, one
JSON object per line, with no verdict
[--logs <dir>] the burrowee daemon's logs dir (default:
<home>/logs beside the transport socket)
[--sid <sid>] only the episodes that took down this sid (or
sid prefix); the other sessions in them stay
listed
[--since <age>] read this far back, an age such as 90m or
168h (default 24h)
exec run one command on a box and exit with its
status (no terminal, no session, stdin
closed)
[<user>@]<box> -- <argv...>
[--burrowee] force the relayed burrowee route, even when
this box also has an ssh route configured
[--ssh <host>] force the ssh route at this host (must
already be in clawee's ssh_config — see
clawee ssh add)
[--timeout <D>] kill the remote command after D (e.g. 30s,
5m) and stop retrying the connection then;
default none
agent headless monitor: print (or --exec on) every
session that wants attention, one at a time
[--exec <command>] run this command per hit with
CLAWEE_SID/ADDR/KIND/TEXT/WRITER set, one at
a time
[--gateway <gateway>] watch this gateway (repeatable; default:
every configured gateway)
[--json] print one JSON object per hit instead of a
line
[--kinds <kinds>] kinds to surface, comma-separated (question
permission idle done waiting working error
chat)
[--once] surface the current backlog, run --exec for
each, and exit
gateways gateways: interactive switch (bare), plus the
scripting verbs (alias: gw)
add add OS users to a gateway (the first ever
added becomes its default)
[user@]<gateway>
[--user <user>] an OS user to add (repeatable; the user@
prefix counts as one)
use switch the active gateway (optionally picking
the user), then attach
<fp|name> [<user>]
list print the local box (name, fp, users), then
the burrowee matrix gateways
[--json]
name set the gateway's local short-name ("-" or
empty clears)
<fp|name> <short>
user grow or shrink the gateway's OS-user list
add <user> add the user to the gateway (and select it)
rm <user> remove the user (clears the selection if it
pointed there)
devices enroll + manage device keys on the gateway
list enrolled keys + the numbered pending queue
(numbers are approve indices)
approve approve a pending knock (bare = the first
asking key)
<#> the pending knock at that number in the queue
<fp> the pending knock with that exact SHA256:
fingerprint
[--label <label>] label for the enrolled key (single token,
[A-Za-z0-9._-]{0,32})
[--role <role>] device role: owner (default) may take a
session's writer role; viewer may only watch,
follow, snapshot and chat
revoke drop an enrolled key or a pending knock
<fp>
role set an enrolled key's device role (viewer =
watch, follow, snapshot, chat — never write)
<fp> <owner|viewer>
ssh manage ssh-forwarded routes to a remote
claweed (no burrowee relay)
add add a new ssh route (an existing host is
refused)
[user@]<host>[:port]
[--socket <path>] path to the remote claweed socket, verbatim —
overrides route.DefaultRemoteSocket()
list list configured ssh hosts and the remote
socket each forwards to
rm remove an ssh route
<host>
relays rank relays, LAN-first (bare: interactive
list; piped: the table)
list print the relay table in effective dial order
probe probe every relay, then print the table
priority move the listed relays to the front of the
manual order
<id…>
skip never auto-dial <id> (at least one relay must
stay enabled)
<id>
use prefer a relay, or one face of it, ahead of
LAN-auto
<id|face>
auto clear the pin — back to LAN-auto order
(re-probes)
gateway show gateways, or switch the active gateway
(alias: gw)
[<id>]
doctor diagnose the local setup; --fix repairs it
[--fix] repair failed checks that clawee owns
(consent-prompted)
[--yes] skip consent prompts (unattended --fix)
update self-update from release.clawee.org (skips
when current)
[--auto] install the update, unattended
[--dry] print the update plan only, then exit
[--force] reinstall even when already on the latest
version
lock-passphrase set the idle-lock passphrase in the local
config
transport choose which burrowee cli this client talks
to (bare: report the current one)
production the production burrowee cli (the default when
the key is absent)
beta the beta burrowee cli installed beside it
auto beta when its socket exists, else production
docs print the full CLI reference as markdown
(docs sites, AI agents)
version print the clawee version (also --version)
Attach flags (bare invocation — no subcommand):
[--burrowee <addr>] reach the box over burrowee via this relay
addr (default: the pinned relay)
[-i <key>] private key file (default: ssh-agent, then
~/.clawee/id_ed25519)
[--reconnect-timeout <deadline>] per-attempt reconnect deadline (default:
config, then 5s)
[-s <sid>] attach the remote session with this sid
directly
[--socket <path>] transport daemon socket path (default:
$BURROWEE_TRANSPORT_SOCK, then config)
[--ssh <host>] reach the box over ssh at this host — needs a
box: clawee <box> --ssh <host>
[--transport <mode>] transport mode: auto|ws|quic (default auto;
empty = daemon default)
[--user <user>] gateway OS user to claim for this run
[--view] open the session read-only (a viewer: live
screen + transcript; t takes the writer role)
In the session picker (this device's sessions, then remote-only ones):
Enter · n attach the selected session · start a new one
s · t stop the session, which stays listed · restart it
p purge the session — the gateway, this device and the list
i pin / unpin the session (pinned sessions stay at the top)
r · w reload the list · watch the session read-only
v · a devices (burrowee, once paired) · authenticate (while not trusted)
g open the box picker (boxes, their users and hosts)
l · q relays (on a burrowee route) · quit
Keys (once attached — keystrokes otherwise pass through to the remote shell):
Ctrl+] open the command composer (type a /command or text; Enter sends)
Ctrl+\ lock the screen (idle-lock passphrase to unlock)
F5 · Ctrl+[ redraw the remote screen in place (Ctrl+[ needs kitty-keyboard)
Shift+F5 redraw the hard way, by reattaching — when the redraw above
· Ctrl+Opt+[ left something behind (/reconnect does the same from the composer)
In the composer:
Enter send the line (text → remote shell; /command → run it)
Shift+Enter insert a newline (multi-line input; needs kitty-keyboard, e.g. Ghostty)
Paste multi-line pastes stay in the box; a pasted file path uploads
the file; very large text is uploaded as a file too
Tab complete the /command
↑ / ↓ recall command history (older / newer)
← / → move the cursor (Home/End or Ctrl+A/E = line start/end · Ctrl+Home/End = buffer)
Backspace · Del delete before / after the cursor (Del = fn+Backspace)
Ctrl+K · Ctrl+U kill to end of line · kill to start (Ctrl+Backspace = kill to start)
Ctrl+L kill the whole line
Ctrl+C clear the box (stays open)
Esc · Ctrl+] close the composer · Ctrl+\ lock
Slash commands (in the composer):
/upload · /download · /name · /relays · /settings · /version
/history pages this session's scrollback · /commands lists what was run in it
/restart · /reconnect · /refresh · /clear · /lock
/detach · /switch · /quit — leave, move to another session, exit
/name renames the session — the remote pty and this device's record
Run 'clawee <command> --help' for a command's own page ('clawee docs' prints the
full reference as markdown).
clawee sessions
list the daemon's pty sessions (--watch streams events, --json prints data)
clawee sessions — list the daemon's pty sessions (--watch streams events, --json prints data)
Usage:
clawee sessions [<command>] [flags]
Commands:
sessions
[--json] print the sessions as a JSON array (one object per session)
instead of the table
[--watch] stream session events until the daemon closes the stream
new create a session headlessly (120x40 by default, no terminal
probe) and print its sid
[<addr-prefix>]
[--aqua] run the session in the desktop login session of the gateway
user (needs that user logged in)
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--cols <N>] pty width in N columns (wins over --preset)
[--cwd <dir>] start the shell in this dir on the gateway
[--json] print {sid,name,gateway,user[,aqua]} instead of the bare sid
[--name <name>] the session's name — refused when the gateway already has
one
[--preset <preset>] geometry preset: default (120x40) or phone (80x30)
[--rows <N>] pty height in N rows (wins over --preset)
[--shell <path>] run this path instead of the gateway user's login shell
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
read print the last N lines of a session's output and exit
<addr>
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[-n <N>] lines to print: N, or all (all = what the gateway's ring
retains, 4 MiB by default — not the whole transcript)
[--raw] print ring bytes with escape codes intact (text mode drops
in-place TUI redraws; use --raw for a TUI). On a LIVE
session this is a real attach: it takes the session over
like an interactive client and resizes it to 200x50. A
closed session replays read-only; exited and interrupted are
refused, because reading one would fork a fresh shell
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
attach follow a session's output — headless, plaintext, stdout only
<addr>
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--handle <name>] socket basename (name) for this attach's handle; default a
short hash of the gateway+sid — for a second attach on one
session; a long name can still push the socket path over the
sun_path limit and is refused; not with --raw
[-n <N>] backlog lines before following: N, or all (what the gateway
retains); not with --raw
[--raw] stream ring bytes with escape codes intact (text mode drops
in-place TUI redraws; a real attach: takes the session over
like an interactive client)
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
send type text and/or named keys into a session (no attach; exit
3 = read-only, another device holds it)
<addr> [text ...]
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--enter] append a carriage return last, after --key (and after
--stdin, when given)
[--key <k[,k...]>] named keys to send after the text (or after --stdin, when
given), comma-separated k[,k...], from enter tab esc up down
left right ctrl-c ctrl-d
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
[--stdin] send stdin bytes verbatim instead of positional text (cannot
combine with text arguments); --enter/--key still apply,
appended after the stdin bytes
upload copy a file or folder to the session's box and print its
absolute remote path
<addr> <path>
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--json] print one JSON object {path,size,sid,gateway} instead of the
bare path
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
screen print the session's current screen (ansi repaint bytes, or
--format text) without attaching
<addr>
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--follow] keep printing a snapshot whenever the screen changes (text
mode separates snapshots with a form feed line) until the
session ends or Ctrl-C
[--format <format>] snapshot format: ansi (the styled repaint bytes, default) or
text (bare rows, for agents)
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
status print the session's attention (kind, source, app, progress,
text, since) without attaching
<addr>
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--json] print {kind, source, app, progress, text, since, state,
opened_kind} as one JSON object
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
take take the session's writer role (waits while the writer is
active; Ctrl-C cancels)
<addr>
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
release give the writer role up without detaching (the session
becomes free)
<addr>
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
signal set the session's attention state
(question|permission|idle|done|waiting|working|error|none)
<addr> <kind> [text ...]
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
chat send a chat message to the session's room, or --history to
read the log
<addr> [text ...]
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--from <N>] with --history: print messages after seq N
[--history] print the chat log instead of sending (one line per message:
seq, time, device, [paste], text)
[--max <N>] with --history: at most N messages (0 = the gateway's
default page)
[--paste] mark the message as pasteable: the writer's client offers a
one-key paste of it into the session
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
purge close (if live), purge and forget the session — same effect
as the picker's p, no confirm
<addr>
[--burrowee] force the relayed burrowee route, even when this box also
has an ssh route configured
[--json] print {sid} instead of a plain "purged <sid>" line
[--ssh <host>] force the ssh route at this host (must already be in
clawee's ssh_config — see clawee ssh add)
drops merge this client's and the burrowee daemon's connection
logs: one verdict per drop episode
[--json] print the merged events of both logs, one JSON object per
line, with no verdict
[--logs <dir>] the burrowee daemon's logs dir (default: <home>/logs beside
the transport socket)
[--sid <sid>] only the episodes that took down this sid (or sid prefix);
the other sessions in them stay listed
[--since <age>] read this far back, an age such as 90m or 168h (default 24h)
Addresses: [user@]gateway[#relay]/session · /session (pinned gateway, its default
user and pinned relay) · user@gateway/session. Session = exact name, else a unique
sid prefix. `sessions new` takes the same grammar without /session.
clawee sessions take
take the session's writer role (waits while the writer is active; Ctrl-C cancels)
clawee sessions take — take the session's writer role (waits while the writer is active; Ctrl-C cancels)
Usage:
clawee sessions take <addr> [flags]
take
<addr>
[--burrowee] force the relayed burrowee route, even when this box also has an ssh route
configured
[--ssh <host>] force the ssh route at this host (must already be in clawee's ssh_config —
see clawee ssh add)
clawee sessions release
give the writer role up without detaching (the session becomes free)
clawee sessions release — give the writer role up without detaching (the session becomes free)
Usage:
clawee sessions release <addr> [flags]
release
<addr>
[--burrowee] force the relayed burrowee route, even when this box also has an ssh
route configured
[--ssh <host>] force the ssh route at this host (must already be in clawee's
ssh_config — see clawee ssh add)
clawee lock-passphrase
set the idle-lock passphrase in the local config
clawee lock-passphrase — set the idle-lock passphrase in the local config Usage: clawee lock-passphrase
See the full generated references: clawee CLI reference · claweed CLI reference.
Docs synced 2026-10-17 against clawee v0.3.46 · claweed v0.3.29 — a partial pass over the guard-aware update and restart, the tab title that shows a session asking for you, and the installer exit codes, on top of the v0.3.42 catch-up. See docs_sync.json for what is not covered.