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