/add

name: add
description: Save a peer's retalk user id (their 32-hex fingerprint), optionally under a local name, so you can message them by name. Use when you have a peer's fingerprint to record. Add --verify to fetch and pin their keys now. If the fingerprint is missing, ask with AskUserQuestion.

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.