Reference / CLI reference

CLI reference

Every lwis command, with its main flags. Run lwis <command> --help for the full list of options.

Global options

Option	What it does
`--runtime-dir <dir>`	The runtime directory of lwisd (default: `$XDG_RUNTIME_DIR/lwis`). Also read from `LWIS_RUNTIME_DIR`. Works with every command.
`--version`	Print the version, for example `lwis 0.11.0+ab12cd3`.

Configuration lives in ~/.config/lwis on Linux ($XDG_CONFIG_HOME/lwis) and in ~/Library/Application Support/lwis on macOS. LWIS_CONFIG_DIR overrides it.

Daemon and installation

Command	What it does
`lwis up`	Run lwisd in the foreground. The service runs this. Hooks and the MCP server never start it. `--idle-exit <minutes>`: exit after that long with no attached session, hosted agent or pending delivery.
`lwis down`	Stop lwisd.
`lwis status`	lwisd's status, as JSON.
`lwis doctor`	Check the installation: directories, socket, service, channel, pairings, browsers.
`lwis install-service`	Write the systemd user unit (Linux) or launchd agent (macOS). `--enable` also enables and starts it.
`lwis install-browser`	Write native-messaging host manifests for the installed browsers. `--chrome-id <id>` (repeatable, or `LWIS_CHROME_EXT_IDS`), `--firefox-id <id>`, `--all` for every supported browser, installed or not.
`lwis setup claude`	Install the Claude Code plugin (embedded in the binary) for every project, and start lwisd. `--remove` uninstalls it, `--no-install` only writes the plugin files, `--channels` prefers channels over the session inbox, `--claude <path>` names the `claude` executable.
`lwis self-update`	Update the binary to the latest release, verified with the key built into it and the DNS record. `--check` only says whether an update exists, `--force` reinstalls the current version (never downgrades), `--skip-dns` skips the DNS cross-check.
`lwis skill`	Print the agent SKILL shipped inside this binary. Prefer it to fetching `/SKILL.md`.

Devices and pairing

Command	What it does
`lwis pair`	Pair a phone or browser: shows a QR code and a pairing link, then the 6-digit code to confirm. `--label <name>` (default: `user@host`), `--print-url` for headless machines (confirm with `lwis devices confirm`). `--open`: one-step browser pairing, opens the capture page with the pairing filled in (`--print-link` only prints that link). Server options: `--signal <ntfy url>`, `--blobs <ntfy \| drop-API origin>`, `--pfx <topic prefix>`, `--tok <ntfy token>` (see self-hosting).
`lwis devices`	List paired devices (same as `lwis devices list`).
`lwis devices rm <id>` \| `--all`	Forget a device: its keys, topics and grant. `--all` forgets every device.
`lwis devices rekey <id>`	Start a rekey with a device now.
`lwis devices confirm <code>`	Confirm a pending pairing by the code both screens show.
`lwis devices trust <id> full\|confirm`	`full`: the device's captures are delivered. `confirm`: each one waits for `lwis accept`. Default: `confirm` for the hosted web app, `full` for the others.
`lwis accept <cid>`	Accept a capture that waits for you (strict mode or a `confirm` device). `/lwis:accept` runs it.

Agent sessions

Command	What it does
`lwis sessions`	List agent sessions (same as `lwis sessions list`).
`lwis sessions strict <sid> on\|off`	Strict mode for a session: its captures wait for `/lwis:accept`.
`lwis attach [sid]`	Make a session reachable from your devices (`/lwis:on` runs it). Without a sid: the Claude Code session the command runs in. `--wake` lets captures start a turn in an idle session, `--allow-replies` sends `lwis_reply` without asking you. `--from-agent <label>` also lets that agent pairing reach it, with `--agent-instruction <text>` saying what its reports may trigger.
`lwis detach [sid]`	Stop a session from being reachable (`/lwis:off`). Its waiting captures are dropped.
`lwis allow <dir>`	Attach every session started in this project directory or below it. Takes `--wake` and `--allow-replies`.
`lwis disallow <dir>`	Remove a directory from the allowlist.
`lwis allowed`	List the allowlisted directories.
`lwis pause`	Kill switch: deliver nothing to any session or hosted agent until `lwis resume`. Captures are acked as queued and kept, up to 24 h.
`lwis resume`	Deliver again, starting with what was queued.
`lwis log`	The audit log: deliveries, replies, attach and detach, pause and resume, trust changes. `-n <N>` / `--lines <N>` (default 40), `--json`.
`lwis replies`	List the replies waiting for your approval, with their text and ids. Run it in a terminal, not through the agent.
`lwis reply-approve [id]`	Send a waiting reply (`/lwis:approve-reply <id>`). Without an id: how many replies wait.
`lwis reply-deny <id>`	Drop a waiting reply.
`lwis statusline`	A status line segment for Claude Code: `📷 lwis` when the session is attached, plus waiting captures, held captures, replies to approve, or `paused`; `📷 lwisd off` in any session when the daemon isn't running. Reads the statusLine JSON on stdin.

Setting LWIS_ATTACH=1 (or wake) in a Claude Code session's environment attaches it when it starts.

Identity, contacts and groups

Command	What it does
`lwis id`	Show your identity (same as `lwis id show`; `--json`).
`lwis id create --name <name>`	Create an identity with lwisd as its keyring, register it with the drop API (proof of work) and publish your card. `--label`, `--signal`, `--pfx`, `--tok` as for `lwis pair`; `--blobs <drop-API origin>` (default: the hosted one).
`lwis id safety <contact>`	The safety number with a contact. `--verify <digits>` marks them verified if the digits match.
`lwis id kit`	Show the 24-word recovery kit, until you confirm a word. `--confirm <N> <word>` confirms word N, then the kit is erased.
`lwis card`	Print your card link (same as `lwis card link`).
`lwis card publish`	Republish your card.
`lwis card rotate`	New card key: the old link stops working, contacts get the new one.
`lwis follow <link>`	Follow someone from their card link, so they can send you captures. `--petname <name>`: your name for them.
`lwis contacts`	Contacts and pending follow requests (`--json`).
`lwis contacts accept <rid>`	Accept a follow request. `--petname <name>`, `--follow-back` to follow them too.
`lwis contacts decline <rid>`	Decline a request. `--tell` tells them (default: silence).
`lwis contacts remove <contact>`	Forget a contact and every session with them.
`lwis contacts block <contact>`	Refuse their captures and drop their sessions. They are not told.
`lwis contacts policy <contact>`	Show what a contact may do. `--agents on\|off`: let their captures reach the hosted agents whose `accept_from` names them (default off).
`lwis groups`	Your groups (`--json`).
`lwis groups create <name>`	Create a group.
`lwis groups rename <name> <new>`	Rename a group.
`lwis groups add <group> <contact>…`	Add contacts who follow you (petnames or ids).
`lwis groups remove <group> <contact>`	Remove a member.
`lwis groups delete <group>`	Delete a group.

Sending, inbox and forwarding

Command	What it does
`lwis open <link>`	Open a share link once: writes the image to a private file and prints its path, the note and the circled zones (JSON). `--reply <text>` answers the sender's browser (up to 1 hour after opening). No pairing needed.
`lwis pair --agent <label>`	Pair another machine's agent instead of a device, named `<label>` here. It prints the link and the `lwis peer add` command for that machine. See Agent to agent.
`lwis peer add <name> <link>`	Pair this machine's agent with another machine, from the link its `lwis pair --agent` printed. `lwis peer list [--json]` shows the peers and the sessions each offers; `lwis peer rm <name>` forgets one.
`lwis send-agent <peer> <image>`	Send an image to a session on a peer that accepts this agent. `--to <session>`, `--note`, `--intent`, `--wait-reply <s>` (prints the whole reply; a reply's file is saved in `--out <dir>`). Asks first; without a terminal, only with `--yes`. Refused while paused, recorded in `lwis log`.
`lwis share <image>`	Share an image as one-time share links, for another agent or a person. Asks first; without a terminal, only with `--yes`. Refused while paused, recorded in `lwis log`. `--note`, `--intent`, `--title`, `--links <N>` (1 to 10), `--prompt` (the message to paste), `--wait-reply <s>`, `--json`.
`lwis send-to <contact> <image>`	Send an image to a contact who follows you. `--group <name> <image>` sends to a group instead (one upload, at most 50 recipient endpoints). `--note`, `--intent`, `--title`, `--url`, `--wait-ack <s>`, `--wait-reply <s>`.
`lwis inbox`	Captures your contacts sent you, and the ones you sent, with acks and replies (`--json`).
`lwis reply <cid> <text>`	Reply to a capture in your inbox.
`lwis forward <cid> --to <session\|agent>`	Forward a capture from your inbox to a Claude session or a hosted agent. Always strict for them; the sender is named. `--note <text>` is your request, `--reply-to-sender` also sends the replies to the original sender (only while their replies rule allows it).
`lwis forwards`	Captures you forwarded, and their replies (`--json`).

Hosted agents

lwis agent is an alias of lwis agents.

Command	What it does
`lwis agents`	The loaded profiles, refused files and pending approvals (same as `lwis agents list`; `--json`).
`lwis agents reload`	Re-read the profiles in `<config>/agents/*.toml`.
`lwis agents check <file>`	Validate a profile file without lwisd.
`lwis agents approve <id>`	Approve a strict agent's pending action, by its approval id (`a_…`).
`lwis agents deny <id>`	Deny it. Pending actions are denied after their timeout anyway.
`lwis agents run -- <cmd>…`	Run a command that speaks the agent contract on one synthetic capture. `--image <file>`, `--note <text>`, `--timeout <s>` (default 60).

See Agent profile format and Hosted agents.

Started for you

You don't normally run these yourself: the Claude Code plugin, other agents or your browser start them.

Command	Started by
`lwis channel`	The Claude Code plugin: the stdio MCP server of a Claude session.
`lwis mcp`	Other MCP agents (Codex, opencode…): generic pull tools. `--agent <name>` is the name shown on your devices (default `mcp`).
`lwis hook-status <busy\|idle>`	The UserPromptSubmit and Stop hooks.
`lwis hook-prompt`	The UserPromptSubmit hook: prints pending captures as additional context.
`lwis hook-register`	The SessionStart hook: hands the session's inbox socket to lwisd.
`lwis hook-unregister`	The SessionEnd hook.
`lwis native-host`	The browser extension, through native messaging.

Testing

These act as a test device instead of your phone. They need a device profile file (--device-profile <file>).

Command	What it does
`lwis device pair <link>`	Pair the test device with a daemon using its pairing link. `--label`, `--user <name>`, `--yes`, `--timeout`.
`lwis send <image>`	Send an image to a session as the test device. `--to <sid \| agent name>` (default: the most recently active session), `--note`, `--intent`, `--circle x,y,r`, `--url`, `--title`, `--target`, `--wait-reply <s>`, `--replies <n>`, `--timeout`.
`lwis device pause`	Ask the daemon to pause delivery, as `lwis pause` does. Any pairing may.
`lwis device resume`	Ask the daemon to resume. Only `full`-trust pairings may.