Daily use
Attaching
Run clawee with no arguments to open the session picker and attach. Flags tune the bare invocation:
claweeOpen the local session picker and attach.clawee <gateway>Select a gateway by name, then pick a session (see gateways).-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).--transport <mode>Force transport: auto | ws | quic (empty = daemon default).--user <user>Gateway OS user to claim for this run.
There is no -r/resume flag on the released binary.
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 — on claweed ≥ v0.1.53 this repaints straight from the session holder, on the main screen too, not just the alt screen; an older holder falls back to the previous app-nudge. (Ctrl+[ needs the kitty keyboard protocol, e.g. Ghostty.)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 — local + remote sessions. Keys below.pairing formThe picker on an unpaired device — see pairing.gateway chooserg, or clawee gateway — see gateways.relay list/relays, clawee relays, or l from the picker / chooser — see relays.devices viewd on the picker's Local tab or in the chooser — see devices.lock screenCtrl+\, an idle timeout, or clawee's startup — see locking.history pager/history — see slash commands.version panel/version — clawee + claweed builds; Esc goes back.In the session picker (not while attached) — these never reach the remote shell:
← → · EnterSwitch the Local / Remote tab · attach the selected session.n · r · x · pNew session · rename · close · purge.lSwitch the gateway's relay right there — a compact list, Enter switches, q backs out.dLocal tab: open the devices view (approve / revoke device keys). On the Remote tab d is detach.gOpen the gateway chooser (only with more than one gateway).q · Ctrl+CQuit clawee.
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.
On the Remote tab the row actions differ — they act on the remote pty, not your local session:
t · xRestart the session · stop it.dDetach whoever is attached (here d is not the devices view).r · p · lRename · purge · relays, same as the Local tab.
A remote session's state, on the Remote tab: 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
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.
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./passphraseSet or clear the passphrase from inside a session.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 dim hint appears once — reconnected while locked — ctrl+[ to
refresh.
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+←/→).↑ / ↓Move between lines; at the top/bottom edge, recall command history.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+CClear the current line · clear the box (stays open).TabComplete the /command.Esc · Ctrl+]Close the composer.Ctrl+\Lock the screen.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 — renames the remote pty./relaysRelay priority & skip — ↑↓ move · K/J prio · s skip · u pin · a auto · p probe · ⏎ choose (switches the live session; see relays)./settingsShow or set client upload limits — /settings [max-upload|async-upload <size>]./historyPage the remote session's command history — ↑↓ or j/k a line, Space/f and b a page, g/G top / bottom, q quits. The pager prints no key bar./versionShow the clawee + claweed build versions (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)./lockLock the screen now — /lock [<passphrase>]./passphraseSet or clear the lock passphrase (masked entry)./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.
clawee
clawee — the Clawee terminal client.
Usage:
clawee [<gateway>] [flags] attach a session (optionally selecting a gateway by name)
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)
[--watch] stream session events until the daemon closes
the stream
gateway gateways: interactive switch (bare), plus the
scripting verbs (alias: gw)
use switch the active gateway (optionally picking
the user), then attach
<fp|name> [<user>]
list print the burrowee matrix gateways with users
+ session counts
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})
revoke drop an enrolled key or a pending knock
<fp>
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>
Attach flags (bare invocation — no subcommand):
use prefer <id> (pin to the front, ahead of
LAN-auto)
<id>
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
docs print the full CLI reference as markdown
(docs sites, AI agents)
version print the clawee version (also --version)
[-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)
[--transport <mode>] transport mode: auto|ws|quic (default auto;
empty = daemon default)
[--user <user>] gateway OS user to claim for this run
In the session picker:
g open the gateway chooser (only with more than one gateway)
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 (Ctrl+[ needs kitty-keyboard, e.g. Ghostty)
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 · /history · /version
/restart · /reconnect · /refresh · /detach · /lock · /passphrase · /quit
/name renames the REMOTE pty; the picker rename (r) renames the local clawee session
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)
clawee sessions — list the daemon's pty sessions (--watch streams events)
Usage:
clawee sessions [flags]
sessions
[--watch] stream session events until the daemon closes the stream
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-08-21 against clawee v0.2.12 · claweed v0.2.4.