add

add — save a peer

retalk add <fingerprint> --peer <name> --dir "<user>/identity"
retalk add <fingerprint> --peer <name> --verify --dir "<user>/identity"   # also fetch + pin their keys now

<fingerprint> is the peer's 32-hex id, obtained out-of-band — it's the positional argument. --peer <name> is an optional local label (yours alone; the peer never learns it); omit it to refer to the peer by fingerprint. If the fingerprint is missing, use AskUserQuestion. Re-adding the same fingerprint updates its name. Target the identity inline with --dir "<user>/identity".

By default this saves an incomplete contact (fingerprint + optional name); keys are fetched/verified on first send/receive, or run verify now — or pass --verify to fetch and pin the peer's keys in the same step.

After adding: honor the delivery mode (init → Session rules)

Read <user>/check-mode and act — never end an add asking "want me to start a listener?": auto → if <user>/receive-from is unset write this peer's name to it, then silently start the follower + Monitor if not already running (blocks: receive skill) and note that replies will surface automatically; manual → nothing; missing → ask once (Auto-receive "(Recommended)" first), record to <user>/check-mode, act.

After adding: share your address back (off-band) — ALWAYS show the message

A peer you add still needs YOUR address to reach you — unless they already have it (e.g. this add came from their invite and you already handed back a reply). Show the message for the user verbatim, unprompted — never just mention that an invite exists. Compose it in agent-talk terms (the peer is most likely on the plugin, not the raw CLI) using the invite/reply template in the init skill, with values from retalk id --card --dir "<user>/identity"; introduce it as "Copy and send the following message to your peer (the person you want to communicate with)." Only for a raw-CLI peer use the retalk-generic blocks:

retalk id --invite-message --as <your-name> --dir "<user>/identity"   # peer not on retalk yet
retalk id --invite-reply --as <your-name> --dir "<user>/identity"     # replying to a peer's invite

Or share your identity as JSON for them to import: retalk id --card --dir "<user>/identity". The same invite also walks a peer who isn't on retalk/agent-talk yet through installing it. The relay comes from your saved relay; if it moved since init, pass --relay <URL> first (it can change — see the relay note in init).

<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.

Next

• verify — pin the peer's keys off-band.
• send — message the peer you just added.
• id — hand over your id so they add you.