add — save a peer

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

A plain add is local and needs no passphrase. --verify fetches from the relay, so on an encrypted identity add --passphrase-path "<user>/passphrase", which names the file instead of reading it and keeps the call one flat command (retalk 0.3.0+; init Session rule 8).

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

Is a manual add still the right step? This skill is for a peer who sent you their fingerprint. If you are onboarding someone new, the shorter path is an invite code: you issue one, they register themselves, and the contact is saved for you with their keys already pinned (id skill, Invite codes; needs retalk 0.3.0 or newer). Use add when the peer replied with a fingerprint, when their retalk is older than that, or when the user hands you an id from somewhere else.

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 → make sure <user>/receive-from covers this peer, then silently start the follower + Monitor (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.

Covering the peer means widening the scope, not only filling a blank. Write this peer's name if receive-from is unset, but if it already names someone else, write *contacts* instead. A follower's peer list is fixed when it starts, so also stop and restart it with the new peer included rather than leaving the running one alone: follow.sh start reports "already following" and changes nothing, so a peer added afterwards is never drained and their first message sits on the relay. invite watch does this for itself when a peer registers with a code.

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)." Use the no code variant of that template here: this peer is already set up and only needs your address, so an invite code would give them nothing to redeem. 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, or issue an invite code so the next peer registers themselves instead.