CLI

The chime binary is a single distributable that runs the CLI, the per-machine daemon (chime daemon), the relay (chime relay), and the MCP server (chime mcp serve) as subcommands of itself. Every command below is real — pulled straight from the CLI’s dispatch table — grouped by workflow rather than alphabetically.

Global flags, before the subcommand:

chime [--json] [--home DIR] [--relay URL] <command> [flags]

• --json — machine-readable output on every command.
• --home DIR — override $CHIME_HOME (default ~/.chime).
• --relay URL — override $CHIME_RELAY_URL (default https://api.chime.sh).

Setup

chime init --local

Starts a local chime-relay instance (self-hosted, zero-knowledge — see Self-host) and prints its URL. Subsequent pairing uses it once you export CHIME_RELAY_URL=... as instructed.

chime pair [<code>]

No arguments: computer-initiated pairing (the normal path). Mints a pairing secret, prints a 6-digit pairing code, a chime.sh/p/<code> backlink, and the machine’s codename (plus a scannable QR window on macOS), then waits for the phone to enter it and confirm. See Quickstart. With a code argument: phone-initiated pairing (legacy path, still supported).

chime register <alias>

Registers a notification alias directly, without sending a message. Most workflows don’t need this — chime notify and chime receive auto-register their alias on first use.

chime unpair [--yes]

Removes the pairing. Prompts for confirmation unless --yes is given.

chime mcp install [--global]

Scaffolds the MCP wiring: writes (or updates) .mcp.json in the current directory, or ~/.claude.json with --global, pointing at chime mcp serve. See MCP.

Messaging

chime notify [--alias <a>] [--kind ping|approval|ack|text] <message>

Sends a notification to the paired phone. --kind defaults to ping; --option <o> (repeatable) adds tappable choices for --kind approval. The alias defaults to the current session’s alias ($CHIME_ALIAS, or a freshly minted one) so it’s automatically the same alias a co-running chime receive --watch is listening on.

chime receive [--alias <a>] [--watch]

Drains queued inbound messages for an alias. Without --watch it prints what’s currently queued and exits; with --watch it stays attached and prints new messages as they arrive (Ctrl-C to stop). This is the CLI equivalent of the MCP chime_receive/chime_wait tools — see MCP.

chime notifications pause|resume|status

Mutes/unmutes the local OS notification banner only — messages and read receipts keep flowing and get stored either way; this just silences the desktop popup.

Diagnostics

chime status

Paired state, machine/peer routing ids, relay URL, transport (ws or long-poll), how long ago the daemon last received something, and registered aliases.

chime doctor

Runs setup health checks — including a receive-loop check that flags a paired daemon whose last receive is suspiciously old, or a stale daemon build — and prints actionable fixes.

chime logs [-n N] [-f] [text]

Tails chimed.log. -n N (default 50) sets the line count, text filters to lines containing it (e.g. a message id, to reconstruct one message’s send/receive/ack lifecycle), -f/--follow streams new lines.

chime diagnostics [--lines N] [--out PATH] [--send URL]

Assembles a redacted support bundle — the safe chime status fields plus recent log lines, never message bodies, ciphertext, keys, or tokens. Prints to stdout by default (local only); --send URL is the explicit opt-in to POST it somewhere.

chime context

Shows Claude Code context-window usage (tokens / percent) for the current working directory, when running under Claude Code.

Dispatch

chime agents list

Lists launchable agents (harnesses the daemon knows how to spawn) and whether each is available on this machine.

chime agents dirs [query]

Lists candidate working directories a new agent could be launched in, optionally filtered by query.

chime new <agent> [dir] [--task <text>] [--model <id>]

Launches <agent> in dir (defaults to the current directory), optionally seeded with a --task description and a --model id. The daemon re-validates dir against its own allowlist before spawning — the CLI never holds that allowlist itself.

Live preview

chime preview

Makes a dev server on this machine reachable from your paired phone over the end-to-end encrypted channel — no public URL, no inbound port, no tunnel provider. Run it in your project directory, next to the running server. See Live preview for the whole round trip, the supported app shapes, and the security model.

chime preview --port <port> [--port <port>…] [--ttl <dur>] [--alias <a>] [--no-card]
chime preview --list
chime preview --revoke <grant-id>|all

• --port <1024-65535> — port to grant. Repeatable, up to 8 ports per grant. Privileged ports (below 1024) are refused, with no override.
• --ttl <duration> — how long the grant lives (default 8h, max 24h), e.g. 90m.
• --alias <a> — the thread to send the preview card on. Defaults to the same alias chime notify would use.
• --no-card — mint the grant without sending a preview card.
• --list — the grants that are live on this machine right now.
• --revoke <id>|all — revoke one grant, or every grant.

Creating a grant sends a preview card to the phone; tapping it opens the preview. Requires a build with live preview compiled in — every v0.9.0-or-newer release asset is (chime version prints <version>+tunnel), a plain from-source build isn’t and says so, v0.8.0 shipped it compiled out of every asset, and v0.7.0 predates the feature entirely. It also needs a WebSocket relay, which the managed relay is and a self-hosted Go relay is not yet.

Self-host

chime relay [-addr :8080] [-db PATH]

Runs the zero-knowledge relay (ciphertext transit + offline queue) in the foreground. -db :memory: for an ephemeral store. See Self-host.

chime daemon [-socket PATH] [-relay URL] [-idle-timeout D]

Runs the per-machine daemon in the foreground, headless. Normally you never run this directly — any other chime command auto-starts it as a background process on first use.

chime menubar

Opt-in macOS menu-bar presence showing daemon/relay status, with Pair a device… and Open Activity log… items. Headless machines and non-macOS/CGo-less builds print a notice and exit cleanly — the daemon is unaffected either way.

chime mcp serve

Runs the MCP stdio server. See MCP for the full tool reference.

Also

• chime version — prints the build version. A binary with live preview compiled in prints <version>+tunnel, which is how a release asset is told apart from a plain from-source build. --json reports the two separately, as an untagged version string plus a tunnel boolean.

Next

• MCP — the MCP tool schemas chime mcp serve exposes.
• Live preview — what chime preview actually opens on the phone, and what it can’t render yet.
• Quickstart — install, pair, first message.