CLI commands

Install the CLI with npm install --global @rply/cli, or run any command with npx @rply/cli <command>. Every command accepts --help.

Global options

Option	Description
--json	Machine-readable JSON output. Put it before the command: rply --json send ….
--channel <key>	Which local channel to use. Defaults to RPLY_CHANNEL, then the default channel.
-V, --version	Print the version.

Durations look like 30s, 10m, 2h or 1d. Options that take JSON (--blocks, --patch, --form) also accept a file path, or - to read from stdin.

Setup

rply guide [topic]

Prints usage instructions written for agents. Topics: setup, basics, ask, blocks, html, pins, apps, secrets, files, or all (everything except setup).

Option	Description
--snippet	Print lines to add to AGENTS.md or CLAUDE.md.

rply init <server-url>

Creates a channel on the server, saves its agent token, and prints a claim link for the person to add it to their account.

Option	Description
--name <name>	Channel name shown in the app. Defaults to the hostname.
--agent-name <name>	This agent’s name in the app. Defaults to the hostname.
--force	Replace a local channel with the same key.

The channel is saved under --channel <key> if given, otherwise a slug of its name. The first channel becomes the default.

rply join <server-url> <code>

Joins a channel created in the app, using the agent code it shows. Takes --agent-name and --force like init.

rply pair

Prints a new claim link while nobody has claimed the channel yet.

rply rename <name>

Sets the name this agent shows in the app.

rply whoami

Shows the server and channel this machine posts to.

rply channels

Lists the channels saved on this machine. The default is marked with *.

• rply channels use <key> makes a channel the default.
• rply channels remove <key> forgets a channel on this machine. It stays on the server.

rply update

Updates the CLI to the latest version with npm install --global @rply/cli@latest.

Messages

rply send [text]

Sends a message. The text supports Markdown.

Option	Description
--title <title>	Bold title above the text.
--blocks <json>	Blocks as a JSON array.
--image <path>	Attach an image. Repeatable.
--file <path>	Attach a file. Repeatable.
--silent	Don’t send a push notification.

Prints the message id.

rply edit <message-id> [text]

Changes a message you sent.

Option	Description
--title <title>	New title.
--blocks <json>	Replace all blocks.
--patch <json>	Update blocks by id, e.g. '{"id":"progress","value":7}'. One object or an array.

rply delete <message-id>

Deletes a message you sent. An unanswered question is withdrawn.

rply inbox

Prints new messages and events from the person and marks them as seen. Answers to questions aren’t included; they come through ask --wait and wait.

Option	Description
--wait	Block until at least one message arrives.
--timeout <duration>	Give up waiting after this long (exit code 2).
--since <seq>	Start after this cursor instead of the stored one.
--peek	Don’t mark messages as seen.

rply listen

Streams messages from the person as they arrive, until stopped with Ctrl+C. With --json, prints one JSON object per line.

rply ack <message-id> [state]

Tells the person you’ve seen a message, are working on it, or are done. state is seen, working (the default) or done.

Questions

rply ask <question>

Asks the person something. Without --choices, --confirm, --form or input blocks, they get a text field.

Option	Description
--title <title>	Bold title above the question.
--choices <list>	Comma-separated choices, e.g. "Publish,Skip". --buttons is an alias.
--multi	Allow picking several choices.
--other	Allow a typed answer besides the choices.
--confirm <label>	A single confirm button.
--danger	Style the choices or confirm button as destructive.
--form <json>	Form fields as a JSON array, asked together. Each field has name, label, type (text, textarea, number, select, toggle), and optionally options, required, placeholder.
--blocks <json>	Blocks to include. Several input blocks ask several questions at once.
--default <value>	Answer to use if the question expires. Comma-separated with --multi.
--expires <duration>	Stop accepting answers after this long. Defaults to --timeout when waiting.
--wait	Block until answered and print the answer.
--timeout <duration>	Give up waiting after this long (exit code 2).

With --wait, one question prints its answer (strings as-is, other values as JSON); several print a JSON object keyed by block id. With --json, it prints { status, answers, message_id }. Without --wait, it prints the question’s id.

Exit codes: 2 if the question expired without a default or --timeout ran out, 3 if it was cancelled.

rply wait <message-id>

Waits for the answer to an earlier question. Takes --timeout.

rply asks

Lists your questions that are still open.

rply cancel <message-id>

Withdraws a question that hasn’t been answered.

Pins and status

rply pin set <key> [text]

Creates or replaces the pinned message with this key. Takes --title, --blocks, --image and --file like send.

rply pin patch <key> [text]

Updates the pinned message with this key. Takes --title and --patch.

rply pin remove <key> · rply pin list

Unpins and deletes a pinned message, or lists them.

rply status set <json>

Replaces the pinned message with key status. Takes a blocks array, or { "blocks": [...] }.

rply status patch <json>

Updates status blocks by id. Takes one patch object or an array.

rply status get

Prints the status message’s body as JSON.

Apps

rply app set <key> <file>

Creates or replaces the app with this key from a single HTML file (or - for stdin). Refuses pages whose inline scripts don’t parse.

Option	Description
--title <title>	Title shown in the app. Defaults to the key.

rply app list · rply app remove <key>

Lists apps, or deletes one.

rply app commands

Shows the folder for command scripts and the commands in it.

rply app call <name> [args]

Runs a command script the way rply serve does, to test it. args is JSON. Takes --dir.

rply serve

Runs command scripts for apps and wakes the agent when the person writes.

Option	Description
--dir <path>	Folder with command scripts. Defaults to the one rply app commands shows.
--on-message <command>	Shell command that wakes the agent when the person writes. Runs once at a time, in the current directory, with the new messages as JSON on stdin and RPLY_CHANNEL set.
--on-message-timeout <duration>	Stop a wake run after this long, 0 for never. Default 1h.
--install	Install as a background service (systemd or launchd) that restarts on crash and reboot. Remembers the current directory, PATH and options.
--uninstall	Stop and remove the background service.

rply respond <call-id> [value]

Answers a rply.agent call from an app. value is JSON, plain text, or - for stdin.

Option	Description
--error <message>	Report a failure instead.

Files

rply file upload <path>

Uploads a file and prints its id, for use in image and file blocks.

rply file get <file-id>

Downloads a file the person attached.

Option	Description
--to <path>	Where to save it. Defaults to its name in the current directory.
--force	Overwrite an existing file.

Secrets

rply secret request <name>

Requests a secret. The value is encrypted on the person’s device and only ever written to --to.

Option	Description
--to <path>	File to write, e.g. .env.
--file	Write the value as the whole file instead of a NAME=value line.
--reason <text>	Why you need it, shown to the person.
--expires <duration>	Stop accepting the secret after this long. Defaults to --timeout when waiting.
--wait	Block until the secret is written.
--timeout <duration>	Give up waiting after this long (exit code 2).

Prints only the file path. Exit codes: 2 if it expired or timed out, 3 if declined or cancelled.

rply secret fetch <id>

Writes a requested secret once the person has provided it. Takes --wait and --timeout.

rply secret cancel <id>

Withdraws a secret request.