# clawee — CLI reference

Generated by `clawee docs` from the binary's own help renderer. Do not edit —
regenerate with `go run ./cmd/clawee docs > docs/cli-help.md`.

## 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 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)

```
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 gateway

gateways: interactive switch (bare), plus the scripting verbs (alias: gw)

```
clawee gateway — gateways: interactive switch (bare), plus the scripting verbs (alias: gw)

Usage:
  clawee gateway [<command>]

Commands:
  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)

Bare `clawee gateway` opens the interactive switch modal on a terminal, and
prints the per-gateway session grouping when piped.
```

## clawee gateway use

switch the active gateway (optionally picking the user), then attach

```
clawee gateway use — switch the active gateway (optionally picking the user), then attach

Usage:
  clawee gateway use <fp|name> [<user>]

  use
        <fp|name> [<user>]
```

## clawee gateway list

print the burrowee matrix gateways with users + session counts

```
clawee gateway list — print the burrowee matrix gateways with users + session counts

Usage:
  clawee gateway list
```

## clawee gateway name

set the gateway's local short-name ("-" or empty clears)

```
clawee gateway name — set the gateway's local short-name ("-" or empty clears)

Usage:
  clawee gateway name <fp|name> <short>

  name
         <fp|name> <short>
```

## clawee gateway user

grow or shrink the gateway's OS-user list

```
clawee gateway user — grow or shrink the gateway's OS-user list

Usage:
  clawee gateway 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>

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})
  revoke                        drop an enrolled key or a pending knock
            <fp>
```

## 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})
```

## 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 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 <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>]

Ids accept an unambiguous prefix of the relay's gateway fingerprint.
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 <id> (pin to the front, ahead of LAN-auto)

```
clawee relays use — prefer <id> (pin to the front, ahead of LAN-auto)

Usage:
  clawee relays use <id>

  use
        <id>
```

## 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 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
```