Reference

The peeza command line

This page is generated from the engine's source: it is the text peeza help prints, and the tool list peeza mcp announces. peeza health prints the build you have.

To start — installing, and what has to be true before the first verb: peeza for AI agents.

peeza help

peeza — the peeza daemon's command line.

usage: peeza <command> [flags]

commands
  send <path…>    send to a device, a team or a nearby machine
  link <path…>    mint a public one-time link and print it
  park <path…>    package it and hold it here: no link, no network contact
  get <link>      redeem a link and receive
  accept <id>     start a held transfer
  ls              list this machine's transfers
  watch           stream every daemon event as JSON lines, one per line
  health          ask whether a daemon is running, and which build
  help            this text

transfers
  pause <id>      hold it
  resume <id>     start it again (accept is the same op, with waiting)
  cancel <id>     stop it, keep the card
  rm <id>         discard the card, its partial file and its archive
  rename <id> <l> relabel it; an empty label clears it
  decline <id>    refuse a team delivery (team receivers only)
  clean           discard every settled card

devices and teams
  devices         your own machines, per the relay
  nearby          who is announcing on this network right now
  paired          who this machine has trusted before
  unpair <id>     forget one of them
  teams           list; then create/rename/delete/invite/kick/rotate/leave/join/auto/get

pairing
  confirm [<id>]  answer a first-contact nearby code (--sas <digits>, --yes-sas, --decline)

account
  whoami          connected, connected-stale, disconnected, or unknown
  connect         all three legs; --provider names the provider
  disconnect      deregisters this machine and DELETES its history (asks first)
  config          config, config get <key>, config set k=v [k=v…]
  quit            stop the daemon

setup
  install-cli     put a peeza symlink on your PATH (--dir, --remove, --force)
  completion      print a completion script: peeza completion zsh|bash
  mcp             speak the Model Context Protocol on stdin/stdout, for agents

flags (all commands)
  --json              machine output: JSON lines on stdout, prose on stderr
  --port <n>          control API port (default 7411, or PEEZA_CTL_PORT)
  --data <dir>        the daemon's data directory (default ~/.peeza)
  --timeout <dur>     how long to wait for the daemon to answer

flags (ls)
  --team <id>         only this team's cards
  --solo              only cards that belong to no team

flags (watch)
  --once              exit when the socket closes instead of reconnecting

flags (send)
  --to <device>       one of your own machines
  --team <id>         fan out to a team
  --nearby <peer>     a device on this network
  --reuse <id>        re-ship an existing card instead of making a new one

flags (get)
  --dest <dir>        where to put it (default: the daemon's download directory)
  --hold              land it paused — download later

flags (get, accept)
  --against <path>    a local file OR FOLDER this is a newer version of: only
                      the parts that changed cross the wire. A folder is
                      matched as the archive it packs to, so name a folder when
                      the incoming payload is one and a file when it is a file.
                      Your peeza tells the SENDER which chunks it already
                      holds, so name something you are content for them to
                      learn about — with a directed send between your own
                      machines, that is nobody.

flags (send, get, accept)
  --sas <digits>      accept a first-contact pairing only if the code matches
  --yes-sas           accept it blind; DEFEATS the man-in-the-middle check

flags (send, link, park, get, accept)
  --wait arm          default: return when the card is actionable
  --wait complete     return when the bytes have arrived
  --no-wait           print the id and exit
  --wait-timeout <d>  give up waiting after this long (0 = no limit)

exit codes
  0  did the thing
  1  refused or failed; the reason is on stderr
  2  usage error, never reached the daemon
  3  no daemon reachable
  4  out of disk space; how much is needed is on stderr
  5  declined, deleted, or a team refusal
  6  the daemon has it; how it ended is not known here. NOT a failure — do not
     retry, or you send it twice. peeza ls and peeza watch are what know.

notes
  send REFUSES with no destination, on purpose: in a window a destination-less
  send mints a public link, and that is the wrong default for a process. Use
  link if a public URL is what you want.
  link prints the URL alone on stdout, so $(peeza link file) is the link.
  accept --against needs a card that has not started: auto-accept is on by
  default, so a directed send begins downloading the moment it arrives. Turn it
  off (peeza config set autoAccept=false) on the machine that will use --against,
  or pause the card first.
  Quote a link when redeeming it: the #k= fragment is the encryption key and an
  unquoted # is a shell comment.
  ls hides team fan-out children — one per recipient machine — because they are
  not cards. watch shows every frame, children included.
  Run as peeza with nothing after it, or bare from a terminal, this prints this
  text and starts nothing. The engine is peezad with flags (peezad --port 7411),
  or peezad with no terminal, as launchd and the apps run it.
  On a Mac a stopped daemon is started through its launchd job, never by forking
  a copy — the bootstrap is what makes its file-access grants stick. On Linux and
  Windows the command line starts nothing: the app starts the engine, or run it
  yourself (peezad --port 7411). With nothing to reach this exits 3 and says so.

The MCP server

peeza mcp speaks the Model Context Protocol on stdin/stdout. Point your agent's MCP configuration at the command peeza mcp; wiring it in is a deliberate opt-in, never a default. These tools read, create a transfer or answer a pairing — none of them destroys anything.

Tool	What it does	Parameters
`peeza_health`	Is a peeza daemon running on this machine, and which build? Answers without a token, so it works even when nothing else does.	none
`peeza_whoami`	Is this machine connected to an account? Returns a state: connected, connected-stale (the relay was unreachable, this is the cached answer), disconnected, or unknown. Unknown is NOT disconnected — it means the daemon cannot tell.	none
`peeza_list`	List this machine's transfers, newest last. Team fan-out children are hidden because they are not cards.	`scope` string — 'solo' for cards in no team, a team id for one team's, omitted for all
`peeza_devices`	The other machines on this account, with whether each is online. Their ids are what peeza_send's 'to' takes. Offline is not a refusal: a send to a machine that is away waits for it and lands when it returns.	none
`peeza_nearby`	Devices announcing on this local network right now. Needs no account, no internet and no relay at all — two machines on one desk or one cafe wifi can move files with the WAN unplugged, at LAN speed. Their ids are what peeza_send's 'nearby' takes. An empty list with a note about the beacon usually means nearby has not been switched on for this machine yet, rather than that nobody is there.	none
`peeza_send`	Send a file or folder to a machine you own, a team, or a device on this network, and wait until it is actually under way. Needs no SSH key, no open port, no port forwarding and no VPN — it crosses NAT on its own and falls back to a relay that carries only ciphertext, so it reaches a laptop on hotel wifi where scp cannot. The recipient machine need not be online: a directed send waits for it and lands when it comes back. Transfers resume across daemon restarts and reboots, so a large one is not lost to a closed lid. Exactly one of to/team/nearby is required — there is no default destination, because a send with none mints a PUBLIC link, and that must be asked for on purpose (use peeza_link).	`nearby` string — a peer id from peeza_nearby, over the local network `path` string, required — absolute path to the file or folder to send `team` string — a team id, to fan out to its members `to` string — one of your own machines, by id from peeza_devices `wait` string — 'arm' (default: return once it is under way) or 'complete' (return once the bytes have arrived)
`peeza_link`	Hand a file to somebody outside your machines: mints an end-to-end-encrypted, single-use URL and returns the transfer card, whose 'link' field is the URL. Use this rather than a cloud drive when the recipient should need no account, no app and no sign-up: they open the link in a browser and the file downloads. The decryption key rides in the URL's #k= fragment, which browsers never send to a server, so the relay only ever holds ciphertext it cannot read — and the link is spent after one fetch. Blocks until the URL exists.	`path` string, required — absolute path to the file or folder
`peeza_park`	Freeze a file into a transfer that is held on this machine: no link, no recipient, no network contact of any kind. The snapshot is taken now, so editing or deleting the source afterwards cannot corrupt what gets sent, and a destination can be given later. Use it when a file is ready before its recipient is.	`path` string, required — absolute path to the file or folder
`peeza_get`	Redeem a peeza link and receive the file onto this machine — no account needed, and it works for a link somebody else minted. The link's #k= fragment carries the decryption key and is mandatory: pass the whole link, unshortened and unquoted-away. A one-time link is spent by the first successful fetch.	`dest` string — directory to put it in; omitted means the daemon's download directory `hold` boolean — land it paused instead of downloading now `link` string, required — the full share link, including the #k= fragment `wait` string — 'arm' (default) or 'complete' to wait for the bytes
`peeza_confirm`	Answer a first-contact pairing question from a nearby device. You must supply the six digits shown on the OTHER machine; they are compared with the ones shown here and the pairing is declined if they differ. There is no way to accept without checking: that comparison is the whole man-in-the-middle protection, and it needs a person who can see both screens. Use decline to refuse.	`decline` boolean — refuse the pairing `id` string — the transfer id waiting to pair; omit if only one is `sas` string — the six digits displayed on the other machine
`peeza_cancel`	Stop a transfer that is under way. The card stays, so you can see what happened.	`id` string, required — the transfer id