clawee — CLI reference
Generated by clawee docs from the binary's own help renderer and published
here verbatim. Synced 2026-10-14 at clawee v0.3.42. Run clawee docs
locally for the same reference as markdown, or fetch
cli-help.md.
See also the claweed CLI reference and the main docs.
There is no help verb — help spellings are flags only: -h / --h / -help / --help.
Every verb rejects stray arguments; a usage refusal exits 2 on clawee, 64 on claweed.
A help spelling after the operands still asks for help: clawee sessions send <addr> --help prints that verb's page.
After -- it is an operand, so clawee sessions send <addr> -- -h sends a literal -h.
Run clawee <command> --help for that command's own page (clawee docs prints the full reference as markdown) — or browse the full generated reference:
clawee CLI reference · claweed 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 status
alias of doctor (read-only) — probe the chain and report
clawee status — alias of doctor (read-only) — probe the chain and report Usage: clawee status
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 new
create a session headlessly (120x40 by default, no terminal probe) and print its sid
clawee sessions new — create a session headlessly (120x40 by default, no terminal probe) and print its sid
Usage:
clawee sessions new [<addr-prefix>] [flags]
new
[<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)
On a rename failure the session still exists: its sid is printed on stderr with
the error, so nothing is orphaned unnamed and unfindable.
--aqua needs the gateway user logged into that machine's desktop; the daemon
decides, so this never checks the client's own OS. An old daemon that silently
drops --aqua is caught after create (the created session is checked, then
closed and purged) rather than handed back as a System session.
clawee sessions read
print the last N lines of a session's output and exit
clawee sessions read — print the last N lines of a session's output and exit
Usage:
clawee sessions read <addr> [flags]
read
<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)
Text mode drops in-place redraws (progress bars, TUIs) — use --raw for those.
`-n all` is as far back as the gateway retains (the scrollback ring), not the
whole transcript. --raw is the ring verbatim: it may carry terminal queries (OSC 7501
program status among them) that the terminal it is printed to will answer.
clawee sessions attach
follow a session's output — headless, plaintext, stdout only
clawee sessions attach — follow a session's output — headless, plaintext, stdout only
Usage:
clawee sessions attach <addr> [flags]
attach
<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)
Headless and plaintext: the session's output arrives as UTF-8 lines on stdout
and nothing else. Every diagnostic — the handle line, a reconnect, a lost
stretch of output, `session closed` — goes to stderr, so a pipe carries only
what the session printed.
A line the session leaves open (a `Continue? [y/N] ` prompt) is terminated
with a newline after 300 ms of silence, so a reader blocked on a line wakes.
The remainder is later printed on its own — no byte is ever sent twice, and
a transport drop resumes from the last line written.
Text mode DROPS in-place redraws: a full-screen TUI repaint has no line form.
Use --raw for a TUI — it streams the ring's bytes with escape codes intact,
and takes the session over like an interactive attach. --raw is a lone
stream: it serves no handle socket and takes no -n. --raw is the ring verbatim:
it may carry terminal queries (OSC 7501 program status among them) that the
terminal it is printed to will answer.
clawee sessions send
type text and/or named keys into a session (no attach; exit 3 = read-only, another device holds it)
clawee sessions send — type text and/or named keys into a session (no attach; exit 3 = read-only, another device holds it)
Usage:
clawee sessions send <addr> [text ...] [flags]
send
<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
clawee sessions upload
copy a file or folder to the session's box and print its absolute remote path
clawee sessions upload — copy a file or folder to the session's box and print its absolute remote path
Usage:
clawee sessions upload <addr> <path> [flags]
upload
<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)
Lands in the authenticated user's upload tree as uploads/<date>/<HH-MM>-<name>-<hex>;
needs claweed v0.1.30 or newer. Prints the path alone on stdout (--json adds size, sid,
gateway) and never types into the session: follow with `sessions send <addr> "Read <path>
and follow it."`. A folder is packed as the composer's /upload packs it.
clawee sessions screen
print the session's current screen (ansi repaint bytes, or --format text) without attaching
clawee sessions screen — print the session's current screen (ansi repaint bytes, or --format text) without attaching
Usage:
clawee sessions screen <addr> [flags]
screen
<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)
Rendered from the gateway's own screen model at the writer's geometry; --follow
keeps printing as the screen changes. Never attaches, never resizes, never types.
clawee sessions status
print the session's attention (kind, source, app, progress, text, since) without attaching
clawee sessions status — print the session's attention (kind, source, app, progress, text, since) without attaching
Usage:
clawee sessions status <addr> [flags]
status
<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)
One line, `<kind> [<app>] [<progress>%] <since> <text>`, or `none`; --json prints one
object that adds the source, the session's state and opened_kind (tui, agent, app, or
empty when unknown). source is program (the program's own OSC 7501 report), hook (an
adapter's `sessions signal`) or heuristic (claweed's quiet-prompt guess). Read-only:
never attaches, never types. Not `clawee status`, which is the doctor alias.
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 sessions signal
set the session's attention state (question|permission|idle|done|waiting|working|error|none)
clawee sessions signal — set the session's attention state (question|permission|idle|done|waiting|working|error|none)
Usage:
clawee sessions signal <addr> <kind> [text ...] [flags]
signal
<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)
clawee sessions chat
send a chat message to the session's room, or --history to read the log
clawee sessions chat — send a chat message to the session's room, or --history to read the log
Usage:
clawee sessions chat <addr> [text ...] [flags]
chat
<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)
clawee sessions purge
close (if live), purge and forget the session — same effect as the picker's p, no confirm
clawee sessions purge — close (if live), purge and forget the session — same effect as the picker's p, no confirm
Usage:
clawee sessions purge <addr> [flags]
purge
<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)
Refuses if this device is currently attached to the session (never attaches in
order to purge). Already gone on the gateway is not an error: local records are
forgotten and this exits 0.
clawee sessions drops
merge this client's and the burrowee daemon's connection logs: one verdict per drop episode
clawee sessions drops — merge this client's and the burrowee daemon's connection logs: one verdict per drop episode
Usage:
clawee sessions drops [flags]
drops
[--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)
Reads the client's conn-<day>.log and burrowee's <home>/logs/conn/<day>/file-NN.log[.gz],
<home> being the transport socket's (<home>/sockets/<name>), or --logs. A drop is put
down to claweed's own closed reason when one precedes it, else to the nearest carrier
event within 10s, else to nothing. A log that is absent, unreadable or malformed is
reported and the rest is read; it never writes. --json prints the events, unjudged.
clawee exec
run one command on a box and exit with its status (no terminal, no session, stdin closed)
clawee exec — run one command on a box and exit with its status (no terminal, no session, stdin closed)
Usage:
clawee exec [<user>@]<box> -- <argv...> [flags]
exec
[<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
Streams the command's stdout and stderr as they arrive and exits with its exit code.
A route or daemon failure exits 255 with one line on stderr (a timeout and a killed
command included); SIGINT/SIGTERM close the stream, which kills the remote command, and
exit 130/143. An unanswered claweed is retried for up to 90s (less under --timeout).
The command runs without a shell and without any rc file: a bare argv[0] is looked up
on /usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin, so give an absolute
path for anything else, or name a shell of your choice as the command. Route and
address as `sessions new`.
clawee agent
headless monitor: print (or --exec on) every session that wants attention, one at a time
clawee agent — headless monitor: print (or --exec on) every session that wants attention, one at a time
Usage:
clawee agent [flags]
agent
[--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
Watches every configured gateway (or each --gateway). A hit is `sid addr kind text
writer`; --exec runs a command per hit with CLAWEE_SID/ADDR/KIND/TEXT/WRITER set,
serialized. The monitor never types: the command reads the session's state with `clawee
sessions status <addr>` and answers with `sessions send`, taking the writer role
only to type.
clawee gateways
gateways: interactive switch (bare), plus the scripting verbs (alias: gw)
clawee gateways — gateways: interactive switch (bare), plus the scripting verbs (alias: gw)
Usage:
clawee gateways [<command>]
Commands:
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)
Bare `clawee gateways` opens the interactive switch modal on a terminal, and
prints the per-gateway session grouping when piped. `clawee gateway` still works.
clawee gateways add
add OS users to a gateway (the first ever added becomes its default)
clawee gateways add — add OS users to a gateway (the first ever added becomes its default)
Usage:
clawee gateways add [user@]<gateway> [flags]
add
[user@]<gateway>
[--user <user>] an OS user to add (repeatable; the user@ prefix counts as one)
clawee gateways use
switch the active gateway (optionally picking the user), then attach
clawee gateways use — switch the active gateway (optionally picking the user), then attach
Usage:
clawee gateways use <fp|name> [<user>]
use
<fp|name> [<user>]
clawee gateways list
print the local box (name, fp, users), then the burrowee matrix gateways
clawee gateways list — print the local box (name, fp, users), then the burrowee matrix gateways
Usage:
clawee gateways list [--json]
list
[--json]
The local row is `local <box name> <fp> <users>`; the fp is derived from the claweed
instance id, so it does not change for the life of the install (`fp unknown` until the first
authenticated hello). A box name, an fp (or a unique prefix, 4+ hex for the local box) and `local` resolve alike in
every address. --json prints [{name, fp, kind: local|burrowee|ssh, users, this_machine}].
clawee gateways name
set the gateway's local short-name ("-" or empty clears)
clawee gateways name — set the gateway's local short-name ("-" or empty clears)
Usage:
clawee gateways name <fp|name> <short>
name
<fp|name> <short>
clawee gateways user
grow or shrink the gateway's OS-user list
clawee gateways user — grow or shrink the gateway's OS-user list
Usage:
clawee gateways user <fp|name> add|rm <user>
user
add <user> add the user to the gateway (and select it)
rm <user> remove the user (clears the selection if it pointed there)
clawee devices
enroll + manage device keys on the gateway
clawee devices — enroll + manage device keys on the gateway
Usage:
clawee devices <list|approve|revoke|role>
Commands:
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>
clawee devices list
enrolled keys + the numbered pending queue (numbers are approve indices)
clawee devices list — enrolled keys + the numbered pending queue (numbers are approve indices) Usage: clawee devices list
clawee devices approve
approve a pending knock (bare = the first asking key)
clawee devices approve — approve a pending knock (bare = the first asking key)
Usage:
clawee devices approve [<#>|<fp>] [flags]
approve
<#> 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
clawee devices revoke
drop an enrolled key or a pending knock
clawee devices revoke — drop an enrolled key or a pending knock
Usage:
clawee devices revoke <fp>
revoke
<fp>
clawee devices role
set an enrolled key's device role (viewer = watch, follow, snapshot, chat — never write)
clawee devices role — set an enrolled key's device role (viewer = watch, follow, snapshot, chat — never write)
Usage:
clawee devices role <fp> <owner|viewer>
role
<fp> <owner|viewer>
clawee ssh
manage ssh-forwarded routes to a remote claweed (no burrowee relay)
clawee ssh — manage ssh-forwarded routes to a remote claweed (no burrowee relay)
Usage:
clawee ssh <add|list|rm>
Commands:
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>
The host is passed to ssh(1) verbatim, so a ~/.ssh/config alias carries its
own user, port, key and ProxyJump. `clawee ssh <host>` to select one is a
separate command. Sub-verbs win: a host literally named add, list or rm
cannot be typed directly here — those words always dispatch this verb — but
stays reachable by giving it a different alias in ~/.ssh/config.
clawee ssh add
add a new ssh route (an existing host is refused)
clawee ssh add — add a new ssh route (an existing host is refused)
Usage:
clawee ssh add [user@]<host>[:port] [flags]
add
[user@]<host>[:port]
[--socket <path>] path to the remote claweed socket, verbatim — overrides
route.DefaultRemoteSocket()
clawee ssh list
list configured ssh hosts and the remote socket each forwards to
clawee ssh list — list configured ssh hosts and the remote socket each forwards to Usage: clawee ssh list
clawee ssh rm
remove an ssh route
clawee ssh rm — remove an ssh route
Usage:
clawee ssh rm <host>
rm
<host>
clawee relays
rank relays, LAN-first (bare: interactive list; piped: the table)
clawee relays — rank relays, LAN-first (bare: interactive list; piped: the table)
Usage:
clawee relays [<command>]
Commands:
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>]
Ids accept an unambiguous prefix of the relay's gateway fingerprint.
The list is one table: a relay, then a row per LAN address it publishes,
each printing the face token `relays use` takes (wss://<ip>@<short-id>).
Bare `clawee relays` opens the interactive list on a terminal, and prints the
table when piped.
clawee relays list
print the relay table in effective dial order
clawee relays list — print the relay table in effective dial order Usage: clawee relays list
clawee relays probe
probe every relay, then print the table
clawee relays probe — probe every relay, then print the table Usage: clawee relays probe
clawee relays priority
move the listed relays to the front of the manual order
clawee relays priority — move the listed relays to the front of the manual order
Usage:
clawee relays priority <id…>
priority
<id…>
clawee relays skip
never auto-dial <id> (at least one relay must stay enabled)
clawee relays skip — never auto-dial <id> (at least one relay must stay enabled)
Usage:
clawee relays skip <id>
skip
<id>
clawee relays use
prefer a relay, or one face of it, ahead of LAN-auto
clawee relays use — prefer a relay, or one face of it, ahead of LAN-auto
Usage:
clawee relays use <id|face>
use
<id|face>
clawee relays auto
clear the pin — back to LAN-auto order (re-probes)
clawee relays auto — clear the pin — back to LAN-auto order (re-probes) Usage: clawee relays auto
clawee relays gateway
show gateways, or switch the active gateway (alias: gw)
clawee relays gateway — show gateways, or switch the active gateway (alias: gw)
Usage:
clawee relays gateway [<id>]
gateway
[<id>]
clawee doctor
diagnose the local setup; --fix repairs it
clawee doctor — diagnose the local setup; --fix repairs it
Usage:
clawee doctor [flags]
doctor
[--fix] repair failed checks that clawee owns (consent-prompted)
[--yes] skip consent prompts (unattended --fix)
clawee update
self-update from release.clawee.org (skips when current)
clawee update — self-update from release.clawee.org (skips when current)
Usage:
clawee update [flags]
update
[--auto] install the update, unattended
[--dry] print the update plan only, then exit
[--force] reinstall even when already on the latest version
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
clawee transport
choose which burrowee cli this client talks to (bare: report the current one)
clawee transport — choose which burrowee cli this client talks to (bare: report the current one)
Usage:
clawee transport [production|beta|auto]
transport
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
The choice is persisted in ~/.clawee/config.json and resolves to a socket only
when no --socket flag, no $BURROWEE_TRANSPORT_SOCK and no explicit `socket`
config key is set — an operator who named one exact daemon by hand keeps it.
clawee docs
print the full CLI reference as markdown (docs sites, AI agents)
clawee docs — print the full CLI reference as markdown (docs sites, AI agents) Usage: clawee docs
clawee version
print the clawee version (also --version)
clawee version — print the clawee version (also --version) Usage: clawee version