wire::cli

Enum Command

pub enum Command {
Show 47 variants    Init {
        handle: String,
        name: Option<String>,
        relay: Option<String>,
        json: bool,
    },
    Whoami {
        json: bool,
        short: bool,
        colored: bool,
    },
    Peers {
        json: bool,
    },
    Send {
        peer: String,
        kind_or_body: String,
        body: Option<String>,
        deadline: Option<String>,
        json: bool,
    },
    Tail {
        peer: Option<String>,
        json: bool,
        limit: usize,
    },
    Monitor {
        peer: Option<String>,
        json: bool,
        include_handshake: bool,
        interval_ms: u64,
        replay: usize,
    },
    Verify {
        path: String,
        json: bool,
    },
    Mcp,
    RelayServer {
        bind: String,
        local_only: bool,
        uds: Option<PathBuf>,
    },
    BindRelay {
        url: String,
        migrate_pinned: bool,
        json: bool,
    },
    AddPeerSlot {
        handle: String,
        url: String,
        slot_id: String,
        slot_token: String,
        json: bool,
    },
    Push {
        peer: Option<String>,
        json: bool,
    },
    Pull {
        json: bool,
    },
    Status {
        peer: Option<String>,
        json: bool,
    },
    Responder {
        command: ResponderCommand,
    },
    Pin {
        card_file: String,
        json: bool,
    },
    RotateSlot {
        no_announce: bool,
        json: bool,
    },
    ForgetPeer {
        handle: String,
        purge: bool,
        json: bool,
    },
    Daemon {
        interval: u64,
        once: bool,
        json: bool,
    },
    PairHost {
        relay: String,
        yes: bool,
        timeout: u64,
        detach: bool,
        json: bool,
    },
    PairJoin {
        code_phrase: String,
        relay: String,
        yes: bool,
        timeout: u64,
        detach: bool,
        json: bool,
    },
    PairConfirm {
        code_phrase: String,
        digits: String,
        json: bool,
    },
    PairList {
        json: bool,
        watch: bool,
        watch_interval: u64,
    },
    PairCancel {
        code_phrase: String,
        json: bool,
    },
    PairWatch {
        code_phrase: String,
        status: String,
        timeout: u64,
        json: bool,
    },
    Pair {
        handle: String,
        code: Option<String>,
        relay: String,
        yes: bool,
        timeout: u64,
        no_setup: bool,
        detach: bool,
    },
    PairAbandon {
        code_phrase: String,
        relay: String,
    },
    PairAccept {
        peer: String,
        json: bool,
    },
    PairReject {
        peer: String,
        json: bool,
    },
    PairListInbound {
        json: bool,
    },
    Session(SessionCommand),
    Identity {
        cmd: IdentityCommand,
    },
    Mesh(MeshCommand),
    Setup {
        apply: bool,
    },
    Whois {
        handle: Option<String>,
        json: bool,
        relay: Option<String>,
    },
    Add {
        handle: String,
        relay: Option<String>,
        local_sister: bool,
        json: bool,
    },
    Up {
        handle: String,
        name: Option<String>,
        json: bool,
    },
    Doctor {
        json: bool,
        recent_rejections: usize,
    },
    Upgrade {
        check: bool,
        json: bool,
    },
    Service {
        action: ServiceAction,
    },
    Diag {
        action: DiagAction,
    },
    Claim {
        nick: String,
        relay: Option<String>,
        public_url: Option<String>,
        hidden: bool,
        json: bool,
    },
    Profile {
        action: ProfileAction,
    },
    Invite {
        relay: String,
        ttl: u64,
        uses: u32,
        share: bool,
        json: bool,
    },
    Accept {
        url: String,
        json: bool,
    },
    Reactor {
        on_event: String,
        peer: Option<String>,
        kind: Option<String>,
        verified_only: bool,
        interval: u64,
        once: bool,
        dry_run: bool,
        max_per_minute: u32,
        max_chain_depth: u32,
    },
    Notify {
        interval: u64,
        peer: Option<String>,
        once: bool,
        json: bool,
    },
}

Variants§

§

Init

Generate a keypair, write self-card, and prepare to pair. (HUMAN-ONLY — DO NOT exec from agents.)

Fields

§handle: String

Short handle for this agent (becomes did:wire:).

§name: Option<String>

Optional display name (defaults to capitalized handle).

§relay: Option<String>

Optional relay URL — if set, also allocates a relay slot in one step (equivalent to running wire init then wire bind-relay <url>).

§json: bool

Emit JSON.

§

Whoami

Print this agent’s identity (DID, fingerprint, mailbox slot).

Fields

§json: bool

§short: bool

Print just <emoji> <nickname> (e.g. 🦊 foxtrot-meadow). Plain text, no ANSI escapes. Useful for piping into other tools.

§colored: bool

Print <emoji> <nickname> wrapped in ANSI 256-color escapes. Drop into a Claude Code statusline command for live identity display.

§

Peers

List pinned peers with their tiers and capabilities.

Fields

§json: bool

§

Send

Sign and queue an event to a peer.

Forms (P0.S 0.5.11): wire send

# kind defaults to “claim” wire send

# explicit kind (back-compat) wire send - # body from stdin (kind=claim) wire send @/path/to/body.json # body from file

Fields

§peer: String

Peer handle (without did:wire: prefix).

§kind_or_body: String

When <body> is omitted, this is the event body (kind defaults to claim). When both this and <body> are given, this is the event kind (decision, claim, etc., or numeric kind id) and the next positional is the body.

§body: Option<String>

Event body — free-form text, @/path/to/body.json to load from a file, or - to read from stdin. Optional; omit to use <kind_or_body> as the body with kind=claim.

§deadline: Option<String>

Advisory deadline: duration (30m, 2h, 1d) or RFC3339 timestamp.

§json: bool

Emit JSON.

§

Tail

Stream signed events from peers.

Fields

§peer: Option<String>

Optional peer filter; if omitted, tails all peers.

§json: bool

Emit JSONL (one event per line).

§limit: usize

Maximum events to read before exiting (0 = stream until SIGINT).

§

Monitor

Live tail of new inbox events across all pinned peers — one line per new event, handshake (pair_drop / pair_drop_ack / heartbeat) filtered by default.

Designed to be left running in an agent harness’s stream-watcher (Claude Code Monitor tool, etc.) so peer messages surface in the session as they arrive, not on next manual wire pull.

See docs/AGENT_INTEGRATION.md for the recommended Monitor invocation template.

Fields

§peer: Option<String>

Only show events from this peer.

§json: bool

Emit JSONL (one InboxEvent per line) for tooling consumption.

§include_handshake: bool

Include handshake events (pair_drop, pair_drop_ack, heartbeat). Default filters them out as noise.

§interval_ms: u64

Poll interval in milliseconds. Lower = lower latency, higher CPU.

§replay: usize

Replay last N events from history before going live (0 = none).

§

Verify

Verify a signed event from a JSON file or stdin (-).

Fields

§path: String

Path to event JSON, or - for stdin.

§json: bool

Emit JSON.

§

Mcp

Run the MCP (Model Context Protocol) server over stdio. This is how Claude Desktop / Claude Code / Cursor / etc. expose wire_send, wire_tail, etc. as native tools.

§

RelayServer

Run a relay server on this host.

Fields

§bind: String

Bind address (e.g. 127.0.0.1:8770).

§local_only: bool

v0.5.17: refuse non-loopback binds, skip phonebook listing, skip .well-known/wire/agent serving. The relay becomes invisible from outside the box — only same-machine processes can pair through it. Right call for within-machine agent coordination where you don’t want metadata leaking to a public relay. Pair this with wire session new which probes 127.0.0.1:8771 and allocates a local slot automatically.

§uds: Option<PathBuf>

v0.7.0-alpha.16: bind to a Unix Domain Socket instead of TCP. When set, –bind is ignored. Implies –local-only semantics (no phonebook, no .well-known). Socket is chmod 0600 (owner- rw only), giving SO_PEERCRED-equivalent same-uid trust for sister sessions. Unix only (Windows refuses).

§

BindRelay

Allocate a slot on a relay; bind it to this agent’s identity.

v0.5.19 (issue #7): if any peers are pinned to this agent’s current slot, this command refuses by default — silent migration silently black-holes their inbound messages. Pass --migrate-pinned to acknowledge the risk and proceed, or use wire rotate-slot (which emits a wire_close event to peers) for safe rotation.

Fields

§url: String

Relay base URL, e.g. http://127.0.0.1:8770.

§migrate_pinned: bool

Acknowledge that pinned peers will black-hole until they re-pin manually. Required when state.peers is non-empty; ignored on fresh boxes. Use wire rotate-slot instead for the supported same-relay rotation path.

§json: bool

§

AddPeerSlot

Manually pin a peer’s relay slot. (Replaces SAS pairing for v0.1 bootstrap; real wire join lands in the SPAKE2 iter.)

Fields

§handle: String

Peer handle (becomes did:wire:).

§url: String

Peer’s relay base URL.

§slot_id: String

Peer’s slot id.

§slot_token: String

Slot bearer token (shared between paired peers in v0.1).

§json: bool

§

Push

Drain outbox JSONL files to peers’ relay slots.

Fields

§peer: Option<String>

Optional peer filter; default = all peers with outbox entries.

§json: bool

§

Pull

Pull events from our relay slot, verify, write to inbox.

Fields

§json: bool

§

Status

Print a summary of identity, relay binding, peers, inbox/outbox queue depth. Useful as a single “where am I” check.

Fields

§peer: Option<String>

Inspect a paired peer’s transport / attention / responder health.

§json: bool

§

Responder

Publish or inspect auto-responder health for this slot.

Fields

§command: ResponderCommand

§

Pin

Pin a peer’s signed agent-card from a file. (Manual out-of-band pairing — fallback path; the magic-wormhole flow is pair-host / pair-join.)

Fields

§card_file: String

Path to peer’s signed agent-card JSON.

§json: bool

§

RotateSlot

Allocate a NEW slot on the same relay and abandon the old one. Sends a kind=1201 wire_close event to every paired peer over the OLD slot announcing the new mailbox before swapping. After rotation, peers must re-pair (or operator runs add-peer-slot with the new coords) — auto-update via wire_close is a v0.2 daemon feature.

Use case: a paired peer turned hostile (T11 in THREAT_MODEL.md — abusive bearer-holder spamming your slot). Rotate → old slot is orphaned → attacker’s leverage gone. Operator pairs again with peers they still want.

Fields

§no_announce: bool

Skip the wire_close announcement to peers (faster but they won’t know where you went).

§json: bool

§

ForgetPeer

Remove a peer from trust + relay state. Inbox/outbox files for that peer are NOT deleted (operator can grep history); pass –purge to also wipe the JSONL files.

Fields

§handle: String

Peer handle to forget.

§purge: bool

Also delete inbox/.jsonl and outbox/.jsonl.

§json: bool

§

Daemon

Run a long-lived sync loop: every seconds, push outbox to peers’ relay slots and pull inbox from our own slot. Foreground process; background it with systemd / & / tmux as you prefer.

Fields

§interval: u64

Sync interval in seconds. Default 5.

§once: bool

Run a single sync cycle and exit (useful for cron-driven setups).

§json: bool

§

PairHost

Host a SAS-confirmed pairing. Generates a code phrase, prints it, waits for a peer to pair-join, exchanges signed agent-cards via SPAKE2 + ChaCha20-Poly1305. Auto-pins on success. (HUMAN-ONLY — operator must read the SAS digits aloud and confirm.)

Fields

§relay: String

Relay base URL.

§yes: bool

Skip the SAS confirmation prompt. ONLY use when piping under automated tests or when the SAS has already been verified by another channel. Documented as test-only.

§timeout: u64

How long (seconds) to wait for the peer to join before timing out.

§detach: bool

Detach: write a pending-pair file, print the code phrase, and exit immediately. The running wire daemon does the handshake in the background; confirm SAS later via wire pair-confirm <code> <digits>. wire pair-list shows pending sessions. Default is foreground blocking behavior for backward compat.

§json: bool

Emit JSON instead of text. Currently only meaningful with –detach.

§

PairJoin

Join a pair-slot using a code phrase from the host. (HUMAN-ONLY.)

Aliased as wire join <code> for magic-wormhole muscle-memory.

Fields

§code_phrase: String

Code phrase from the host’s pair-host output (e.g. 73-2QXC4P).

§relay: String

Relay base URL (must match the host’s relay).

§yes: bool

§timeout: u64

§detach: bool

Detach: see pair-host --detach.

§json: bool

Emit JSON instead of text. Currently only meaningful with –detach.

§

PairConfirm

Confirm SAS digits for a detached pending pair. The daemon must be running for this to do anything — it picks up the confirmation on its next tick. Mismatch aborts the pair.

Fields

§code_phrase: String

The code phrase the original wire pair-host --detach printed.

§digits: String

6 digits as displayed by wire pair-list (dashes/spaces stripped).

§json: bool

Emit JSON instead of human-readable text.

§

PairList

List all pending detached pair sessions and their state.

Fields

§json: bool

Emit JSON instead of the table.

§watch: bool

Stream mode: never exit; print one JSON line per status transition (creation, status change, deletion) across all pending pairs. Compose with bash while read to react in shell. Implies –json.

§watch_interval: u64

Poll interval in seconds for –watch.

§

PairCancel

Cancel a pending pair. Releases the relay slot and removes the pending file.

Fields

§code_phrase: String

§json: bool

§

PairWatch

Block until a pending pair reaches a target status (default sas_ready), or terminates (finalized = file removed, aborted, aborted_restart), or the timeout expires. Useful for shell scripts that want to drive the detached flow without polling pair-list themselves.

Exit codes: 0 — reached target status (or finalized, if target was sas_ready) 1 — terminated abnormally (aborted, aborted_restart, no such code) 2 — timeout

Fields

§code_phrase: String

§status: String

Target status to wait for. Default: sas_ready.

§timeout: u64

Max seconds to wait.

§json: bool

Emit JSON on each status change (one per line) instead of just on exit.

§

Pair

One-shot bootstrap. Inits identity (idempotent), opens pair-host or pair-join, then registers wire as an MCP server. Single command from nothing to paired and ready — no separate init/pair-host/setup steps. Operator still must confirm SAS digits.

Examples: wire pair paul # host a new pair on default relay wire pair willard –code 58-NMTY7A # join paul’s pair

Fields

§handle: String

Short handle for this agent (becomes did:wire:). Used by init step if no identity exists; ignored if already initialized.

§code: Option<String>

Code phrase from peer’s pair-host output. Omit to be the host (this command will print one for you to share).

§relay: String

Relay base URL. Defaults to the laulpogan public-good relay.

§yes: bool

Skip SAS prompt. Test-only.

§timeout: u64

Pair-step timeout in seconds.

§no_setup: bool

Skip the post-pair setup --apply step (don’t register wire as an MCP server in detected client configs).

§detach: bool

Run via the daemon-orchestrated detached path (auto-starts daemon, exits immediately, daemon does the handshake). Confirm via wire pair-confirm <code> <digits> from any terminal. See pair-host --detach for details.

§

PairAbandon

Forget a half-finished pair-slot on the relay. Use this if pair-host or pair-join crashed (process killed, network blip, OOM) before SAS confirmation, leaving the relay-side slot stuck with “guest already registered” or “host already registered” until the 5-minute TTL expires. Either side can call. Idempotent.

Fields

§code_phrase: String

The code phrase from the original pair-host (e.g. 58-NMTY7A).

§relay: String

Relay base URL.

§

PairAccept

Accept a pending-inbound pair request (v0.5.14). Explicit alias for the bilateral-completion path that wire add <peer>@<relay> also drives — but doesn’t require remembering the peer’s relay domain (the relay coords come from the stored pair_drop). Errors if no pending-inbound record exists for that peer.

Fields

§peer: String

Bare peer handle (without @<relay>).

§json: bool

Emit JSON.

§

PairReject

Reject a pending pair request (v0.5.14). When someone runs wire add you@<your-relay> against your handle, their signed pair_drop lands in pending-inbound — visible via wire pair-list. Run wire pair-reject <peer> to delete the record without pairing. The peer never receives our slot_token; from their side the pair stays pending until they time out.

Fields

§peer: String

Bare peer handle (without @<relay>).

§json: bool

Emit JSON.

§

PairListInbound

Programmatic-shape list of pending-inbound pair requests (v0.5.14). --json returns a flat array (matching the v0.5.13-and-earlier pair-list --json shape but for inbound). Use this in scripts that need to enumerate inbound pair requests without parsing the SPAKE2 table format from wire pair-list.

Fields

§json: bool

Emit JSON.

§

Session(SessionCommand)

Manage isolated wire sessions on this machine (v0.5.16).

Each session = its own DID + handle + relay slot + daemon + inbox/ outbox tree. Use when multiple agents (e.g. Claude Code sessions in different projects) run on the same machine — without sessions they all share one identity and race the inbox cursor.

Names are derived from basename(cwd) and cached in a registry, so re-entering the same project reuses the same identity.

§

Identity

Manage this session’s identity display layer (character override). v0.7.0-alpha.3: agents can rename themselves — operator or Claude itself picks a custom nickname + emoji that overrides the auto-derived hash-based defaults.

Fields

§cmd: IdentityCommand

§

Mesh(MeshCommand)

v0.6.3 (issues #18 / #19 / #20 / #21): orchestration verbs for the sister-session mesh. wire mesh status is the live view of every paired sister (alias for wire session mesh-status); wire mesh broadcast fans one signed event to every pinned peer.

§

Setup

Detect known MCP host config locations (Claude Desktop, Claude Code, Cursor, project-local) and either print or auto-merge the wire MCP server entry. Default prints; pass --apply to actually modify config files. Idempotent — re-running is safe.

Fields

§apply: bool

Actually write the changes (default = print only).

§

Whois

Show an agent’s profile. With no arg, prints local self. With a nick@domain arg, resolves via that domain’s .well-known/wire/agent endpoint and verifies the returned signed card before display.

Fields

§handle: Option<String>

Optional handle (nick@domain). Omit to show self.

§json: bool

§relay: Option<String>

Override the relay base URL used for resolution (default: https://<domain> from the handle).

§

Add

Zero-paste pair with a known handle. Resolves nick@domain via that domain’s .well-known/wire/agent, then delivers a signed pair-intro to the peer’s slot via /v1/handle/intro. Peer’s daemon completes the bilateral pin on its next pull (sends back pair_drop_ack carrying their slot_token so we can wire send to them).

Fields

§handle: String

Peer handle (nick@domain), OR a bare sister-session name when --local-sister is set.

§relay: Option<String>

Override the relay base URL used for resolution.

§local_sister: bool

v0.6.6: pair with a sister session on this machine without touching federation. Looks up handle as a session name in wire session list, reads that session’s agent-card + endpoints from disk, pins directly, then delivers the pair_drop to the sister’s local-relay slot. No .well-known resolution; reserved nicks (wire, slancha, etc.) are addressable because they don’t need a federation claim.

§json: bool

§

Up

One-shot full bootstrap — wire up <nick@relay-host> does in one command what 0.5.10 took five (init + bind-relay + claim + daemon- background + remember-to-restart-on-login). Idempotent: re-run on an already-set-up box prints state without churn.

Examples: wire up paul@wireup.net # full bootstrap wire up paul-mac@wireup.net # ditto, nick = paul-mac wire up paul # bootstrap, default relay

Fields

§handle: String

Full handle in nick@relay-host form, or just nick (defaults to the configured public relay wireup.net).

§name: Option<String>

Optional display name (defaults to capitalized nick).

§json: bool

§

Doctor

Diagnose wire setup health. Single command that surfaces every silent-fail class — daemon down or duplicated, relay unreachable, cursor stuck, pair rejections piling up, trust ↔ directory drift. Replaces today’s 30-minute manual debug.

Exit code non-zero if any FAIL findings.

Fields

§json: bool

Emit JSON.

§recent_rejections: usize

Show last N entries from pair-rejected.jsonl in the report.

§

Upgrade

Atomic upgrade: kill every wire daemon process, spawn a fresh one from the current binary, write a new pidfile. Eliminates the “stale binary text in memory under a fresh symlink” bug class that burned 30 minutes today.

Fields

§check: bool

Report drift without taking action (lists processes that would be killed + the version of each).

§json: bool

§

Service

Install / inspect / remove a launchd plist (macOS) or systemd user unit (linux) that runs wire daemon on login + restarts on crash. Replaces today’s “background it with tmux/&/systemd as you prefer” footgun.

Fields

§action: ServiceAction

§

Diag

Inspect or toggle the structured diagnostic trace ($WIRE_HOME/state/wire/diag.jsonl). Off by default. Enable per process via WIRE_DIAG=1, or per-machine via wire diag enable (writes the file knob a running daemon picks up automatically).

Fields

§action: DiagAction

§

Claim

Claim a nick on a relay’s handle directory. Anyone can then reach this agent by <nick>@<relay-domain> via the relay’s .well-known/wire/agent endpoint. FCFS; same-DID re-claims allowed.

Fields

§nick: String

§relay: Option<String>

Relay to claim the nick on. Default = relay our slot is on.

§public_url: Option<String>

Public URL the relay should advertise to resolvers (default = relay).

§hidden: bool

v0.5.19 (#9.1): opt out of the relay’s bulk /v1/handles directory listing. The handle stays claimed (FCFS still applies) and direct .well-known/wire/agent?handle=X lookup still resolves, so peers you share the handle with out-of-band can still pair. Bulk scrapers / phonebook crawlers will not see the nick. Use this for handles meant for known-peer pairing only — see issue #9.

§json: bool

§

Profile

Edit profile fields (display_name, emoji, motto, vibe, pronouns, avatar_url, handle, now). Re-signs the agent-card atomically.

Examples: wire profile set motto “compiles or dies trying” wire profile set emoji “🦀” wire profile set vibe ‘[“rust”,“late-night”,“no-async-please”]’ wire profile set handle “coffee-ghost@anthropic.dev” wire profile get

Fields

§action: ProfileAction

§

Invite

Mint a one-paste invite URL. Anyone with this URL can pair to us in a single step (no SAS digits, no code typing). Auto-inits + auto-allocates a relay slot on first use. Default TTL 24h, single-use.

Fields

§relay: String

Override the relay URL for first-time auto-allocation.

§ttl: u64

Invite lifetime in seconds (default 86400 = 24h).

§uses: u32

Number of distinct peers that can accept this invite before it’s consumed (default 1).

§share: bool

Register the invite at the relay’s short-URL endpoint and print a curl ... | sh one-liner the peer can run on a fresh machine. Installs wire if missing, then accepts the invite, then pairs.

§json: bool

Emit JSON.

§

Accept

Accept a wire invite URL. Single-step pair — pins issuer, sends our signed card to issuer’s slot. Auto-inits + auto-allocates if needed.

Fields

§url: String

The full invite URL (starts with wire://pair?v=1&inv=...).

§json: bool

Emit JSON.

§

Reactor

Long-running event dispatcher. Watches inbox for new verified events and spawns the given shell command per event, passing the event JSON on stdin. Use to wire up autonomous reply loops: wire reactor –on-event ‘claude -p “respond via wire send”’ Cursor persisted to $WIRE_HOME/state/wire/reactor.cursor.

Fields

§on_event: String

Shell command to spawn per event. Event JSON written to its stdin.

§peer: Option<String>

Only fire for events from this peer.

§kind: Option<String>

Only fire for events of this kind (numeric or name, e.g. 1 / decision).

§verified_only: bool

Skip events whose verified flag is false (default true).

§interval: u64

Poll interval in seconds.

§once: bool

Process one sweep and exit.

§dry_run: bool

Don’t actually spawn — print one JSONL line per event for smoke-testing.

§max_per_minute: u32

Hard rate-limit: max events handler is fired for per peer per minute. 0 = unlimited. Default 6 — covers normal conversational tempo, kills LLM-vs-LLM feedback loops (which fire 10+/sec).

§max_chain_depth: u32

Anti-loop chain depth. Track event_ids this reactor emitted; if an incoming event body contains (re:X) where X is in our emitted log, skip — that’s a reply-to-our-reply, depth ≥ 2. Disable with 0.

§

Notify

Watch the inbox for new verified events and fire an OS notification per event. Long-running; background under systemd / & / tmux. Cursor is persisted to $WIRE_HOME/state/wire/notify.cursor so restarts don’t re-emit history.

Fields

§interval: u64

Poll interval in seconds.

§peer: Option<String>

Only notify for events from this peer (handle, no did: prefix).

§once: bool

Run a single sweep and exit (useful for cron / tests).

§json: bool

Suppress the OS notification call; print one JSON line per event to stdout instead (for piping into other tooling or smoke-testing without a desktop session).