Id

id — your address (fingerprint)

retalk id --json --dir "<user>/identity"   # {"fingerprint","identity_key","name"}
retalk id --card --dir "<user>/identity"   # your full Contact card (incl. relay) — shareable; peer saves it via import
retalk id --invite-message --as <name> --dir "<user>/identity"   # a copy-paste invite to onboard a peer off-band
retalk id --invite-reply --as <name> --dir "<user>/identity"     # a paste-back reply: hands an inviter your address
retalk invite new --dir "<user>/identity"                        # mint an invite code so a peer can register themselves

The fingerprint is your address and pin in one — safe to post publicly; share it out-of-band. Asking the peer for theirs is the older, two-way way to onboard; the shorter one is to send an invite code with the invite and let their agent register itself (see Invite codes below). --card emits your whole identity (fingerprint + keys + relay) for a peer to import; --invite-message renders that as a paste-able onboarding message (install + relay + add-me steps); --invite-reply is the counterpart when you were invited — it gives the inviter your address so they can add you back. Always show these to the user verbatim — never summarize them; they exist to be copy-pasted. Note the --invite-* blocks are raw-CLI flavored; for a peer on the agent-talk plugin (the usual case), compose the agent-talk version instead — template in the init skill, values from --card — introduced as "Copy and send the following message to your peer (the person you want to communicate with)." Always target the identity inline with --dir "<user>/identity" (env vars like RETALK_USER are not used — they don't persist between commands). Encrypted identity? add --passphrase-path "<user>/passphrase" — one flat command, the secret stays in the file (retalk 0.3.0+; init Session rule 8 has the older-retalk fallback). No relay contact.

<user> = this session's user directory — an absolute path resolved at init (e.g. ~/.agent-talk/users/alice (global) or <project>/.agent-talk/users/alice (local)). Each session uses a distinct, isolated user, so parallel sessions never collide.

Invite codes — let a peer register themselves

Without a code, onboarding runs in both directions: you invite a peer, they set up, they send their fingerprint back, and you add it by hand. An invite code closes that loop. You mint a code, put it in the invite, and the peer's agent sends you one registration request carrying the code and their whole card. Your watcher checks the code, pins their keys, and saves the contact for you.

What a code proves, exactly. A valid code shows the sender was authorised by whoever issued it. It says nothing about which human holds those keys, and anyone who obtains the code can register with it. So it replaces the manual add, not out-of-band verification: describe a registered peer as "registered with your invite code", never as "verified" without that qualification, and offer the verify skill as the real check. Treat a code as a secret while it is live, hand it over the same off-band channel as the invite, and revoke one that leaks.

Version floor: retalk 0.3.0. Everything in this section needs it. On an older retalk these commands do not exist, so fall back to the manual path: a codeless invite, the peer replies with their fingerprint, you add them. Both templates are in the init skill. Check once, and say which path you took:

retalk invite --help >/dev/null 2>&1 && echo "invite codes available" \
  || echo "retalk too old for invite codes; use the manual add path"

(The init skill's install-or-upgrade step normally makes this moot; if it reports too old, run that step first.)

Issue a code (inviter)

Single-use is the default. Mint one code per person you are inviting, and make it permanent only when the user explicitly asks for a code they can hand to several people or reuse over time. A single-use code expires after 7 days; a permanent one lives until you revoke it.

retalk invite new --dir "<user>/identity"                       # single-use, expires in 7 days
retalk invite new --peer <name> --dir "<user>/identity"         # pre-assign the local name the contact is saved under
retalk invite new --permanent --dir "<user>/identity"           # multi-use until revoked; only when asked for
retalk invite new --expires <days> --dir "<user>/identity"      # override the expiry (0 = never)
# stdout, one JSON object: {"code","kind":"single"|"permanent","expires","peer"}

Pass --peer <name> whenever you already know who the invite is for: the contact then lands under that local name instead of whatever name the requester suggests for themselves. Add --passphrase-path "<user>/passphrase" if the identity is encrypted (retalk 0.3.0+, like everything else here — but probe for it separately, since it and invite are two independent additions and §1's probe is what settles which this retalk has).

Take code from that JSON and put it in the invite message (template in the init skill). Then start the watcher below in the same turn. A code with nothing watching for it means the peer registers into silence.

For a peer on the raw retalk CLI with no coding agent, retalk renders its own invite text with the code appended:

retalk id --invite-message --code <code> --as <name-they-save-you-as> --dir "<user>/identity"

See and revoke codes

retalk invite list --dir "<user>/identity"                # human table
retalk invite list --json --dir "<user>/identity"         # NDJSON, one object per code
# {"code","kind","peer","created","expires","uses","used_by":[...],"revoked","active"}
retalk invite revoke <code> --dir "<user>/identity"       # deactivate; exit 2 + "[retalk] no such invite code" if unknown

active means not revoked, not expired, and either permanent or still unused. Revoke a code the moment the user says it went to the wrong place.

Watch for registrations (inviter)

retalk invite watch reads pending mail from unknown senders only and acts on contact requests. Mail from a saved contact is never touched; it stays for a normal receive. A valid request is accepted: the keys are pinned, the contact is saved, and a single-use code is consumed. An invalid one is refused, so the sender's outbox stops resending it. Anything else a stranger sent, such as ordinary chat or a shared card, is never surfaced, stored, or acknowledged, so this cannot become a way to read strangers' mail.

The watcher does not compete with your message reader. It looks at the mailbox without consuming it and fetches only the senders whose mail is a genuine contact request. Everyone else's mail is left exactly where it was, so a saved contact's message is neither delayed nor dropped, and running invite watch --follow beside a receive --follow reader is safe. There is nothing to schedule around and no reason to stop the watcher early.

This is the one thing that needs a modern relay, not just a modern client. Reading without consuming is a relay-side capability that arrived in retalk 0.3.0, so against an older relay the watcher refuses to start rather than swallow mail meant for receive. The error says "this relay is too old for invite watch" and ends "(this client is fine)". Take that at face value: upgrading the local retalk changes nothing. The public relay https://relay.retalk.dev is already new enough. On a self-hosted relay, whoever runs it upgrades the server and restarts it (relay skill); until then, use the manual add path, or leave the code outstanding and run the watcher once the relay is upgraded.

One-shot check (emits no records and exits when nothing is pending; it still prints a short banner on stderr unless you add --quiet):

retalk invite watch --dir "<user>/identity"

invite watch <start|stop|status> — the background watcher, which feeds the plugin's contact-request spool so registrations surface in the session the way messages do. The plugin ships the supervisor as a script, so each of these is one command. Start it right after issuing a code:

<plugin>/bin/invite-watch.sh start "<user>" --passphrase-path "<user>/passphrase"

<plugin>/bin/invite-watch.sh stop "<user>"
<plugin>/bin/invite-watch.sh status "<user>"

• <plugin> is this plugin's root (${CLAUDE_PLUGIN_ROOT} under Claude Code). The script finds the spool writer beside itself and restarts retalk invite watch if it dies; the pid file (<user>/invite-watch.pid) and stderr log (<user>/invite-watch.err) are the same as before.
• The watcher decrypts, so an encrypted identity needs the passphrase; naming the file with --passphrase-path keeps the secret out of the command and the environment. Drop the flag on a --no-passphrase identity, and drop it too if §1's probe reported a retalk without it (export RETALK_PASSPHRASE in the same shell before calling the script instead).
• The default --interval 10 is a calm rate while a code is outstanding; retalk polls every 2 seconds if left to itself. Stopping it once every code is redeemed or revoked is tidiness, not a requirement: it costs a little polling and nothing else, and leaving it running does not affect message delivery.
• status also prints the tail of this session's request spool, so it answers "is it running and who has registered" in one call.
• The spool writer's --stream requests keeps these records in <user>/sessions/<session-id>.requests.ndjson, separate from message mail, and the plugin's retalk-requests monitor pushes each new line into the session. On hosts without that monitor (see init's Adapt to your host agent), read the spool with the status block above.