Skip to main content
← Back to list
01Issue
FeatureClosedSwamp ClubPublic
AssigneesNone

Relationships

#2186 Docs: document the swamp invite command group and referral links in content/manual

Opened by skunk-ape · 9/16/2026

Gap

content/manual/ has no page covering the swamp invite command group or referral links. content/manual/reference/issue-commands.md documents the sibling swamp issue group, so there is a clear precedent and a clear empty slot next to it.

This is a follow-up to swamp-club lab issue #2180 (CLI: swamp invite link / rule1), which adds the command group to the swamp CLI, and lab #2179, which adds the server side (POST /api/v1/referral-link, the /r/<code> landing route, and the points payout).

What needs documenting

A reference page — suggested content/manual/reference/invite-commands.md, mirroring the shape of issue-commands.md:

  • swamp invite — prints group help.
  • swamp invite link (alias swamp invite rule1) — fetches, creating on first use, the operative's referral link and prints it. Idempotent: the same operative always gets the same link.
    • Log mode: the bare URL alone on stdout, with the points note on stderr, so swamp invite link | pbcopy captures only the link. This split is deliberate and worth stating explicitly in the docs.
    • --json: emits {code, url}.
    • Requires authentication (swamp auth login or SWAMP_API_KEY); the referral link is identity-scoped.
  • swamp invite <address> — per-address email invite, tracked in lab #1376. Until that lands, this path reports on stderr that no invite was sent, prints the referral link as a substitute, and exits non-zero. Its --json output carries comingSoon: true and invitedEmail: null alongside {code, url}.

Note on timing

The <address> behaviour above is temporary and changes when lab #1376 ships — at that point the command starts exiting 0, the stderr notice goes away, and the comingSoon / invitedEmail JSON fields are removed. Either document it as the current state and revisit, or hold that section until #1376 lands. The rest of the page is stable and can be written now.

  • swamp-club lab #2180 — CLI command (this feature)
  • swamp-club lab #2179 — API, landing route, payout
  • swamp-club lab #1376 — per-address email invite
  • A parallel UAT coverage issue is being filed in swamp-club/swamp-uat.
02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

9/18/2026, 4:24:24 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

skunk-ape commented 9/16/2026, 6:24:49 PM

Correction after review: the alias was renamed from rule1 to first-rule before the CLI change landed. Everywhere this issue says swamp invite rule1, read swamp invite first-rule. Nothing else about the described behaviour changes.

skunk-ape commented 9/16/2026, 11:00:48 PM

Scope reduction: the [email] positional has been removed from swamp invite before shipping. The manual page should document only swamp invite (group help), swamp invite link, and its first-rule alias.

Please disregard the bullet describing swamp invite <address> and its coming-soon behaviour — there is no such path, no comingSoon/invitedEmail JSON fields, and no non-zero exit to document. The "Note on timing" section is likewise moot, so the whole page can be written now without waiting on lab #1376.

Rationale: a surface that parses an address only to say "not built yet" advertises something that does not exist, and the recruit link may be enough on its own.

stack72 commented 9/18/2026, 4:24:16 PM

Already documented — invite-commands.md exists. Bugs in that page were fixed under #2258 in #1234.

Sign in to post a ripple.