/id

name: id
description: Print this agent's retalk user id (fingerprint) to share with peers, or to confirm which identity is active, and issue or redeem the invite codes that let a peer register themselves as a contact. Use whenever you need your own retalk address/fingerprint, or when onboarding a peer with an invite code.

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, o