Skip to main content

INBOX COMMANDS

The swamp inbox command group reads your Swamp Club inbox from the terminal. It holds the same messages as the /inbox page, and read state is shared: reading a message in one marks it read in the other. Which messages appear, and how many can be sent to you in a day, is described under Terminal inbox.

Both commands need a swamp-club.com account, like any other command — see Swamp Account Requirement — and both run outside a Swamp repository. The inbox belongs to a person: a collective API key has no inbox.

swamp inbox

List your inbox, newest first.

swamp inbox

In a terminal

When stdin and stdout are both a terminal, swamp inbox opens a picker:

─swamp───────────────────────────────────────────────────────────────── inbox ──
> ▏                                                                        6 / 6
────────────────────────────────────────────────────────────────────────────────
 ●  2026-10-28  system        New quest tier unlocked
  ●  2026-10-28  direct        Welcome to the collective
  ●  2026-10-28  announcement  Office hours on Thursday
     2026-10-28  system        Your trial ends in 3 days
     2026-10-28  direct        Thanks for the bug report
     2026-10-28  announcement  Swamp 2026.11 is out

────────────────────────────────────────────────────────────────────────────────
 system · 2026-10-28
 New quest tier unlocked
 Check your progress.
 Next:  swamp quest

────────────────────────────────────────────────────────────────────────────────
↑/↓ navigate  Ctrl-u/d scroll preview  Ctrl-r mark read  Ctrl-a mark all read
Enter select  Esc cancel

Each row shows the date, kind and title, with ● on unread messages. The highlighted row is drawn in reverse video; in the sample above, it is the first row, which starts one column further left. Typing filters the rows by title and kind. The preview shows the highlighted message whole: kind and date, title, body, then its Link: and Next: lines. Previewing marks nothing read.

Key Does
↑ / ↓ Move the highlight
Ctrl-u / d Scroll the preview up or down
Enter Open the message: mark it read, close the picker and leave the message in the scrollback
Ctrl-r Mark the highlighted message read and close
Ctrl-a Mark every unread message on the loaded page read, including rows the filter hides, and close
Esc Close and change nothing

Ctrl-r and Ctrl-a end with how many messages they marked, for example Marked 2 messages read. Like every action key, Ctrl-a acts only while at least one row is showing, so it does nothing while the filter matches none.

The picker loads one page of read and unread messages, so a read message can be opened again. When older messages exist, it ends, whatever you chose, with:

To see older:  swamp inbox --all --before <id>

An empty inbox opens no picker and prints Your inbox is empty. The picker never runs a message's suggested command.

Outside a terminal

When stdin or stdout is not a terminal, or with --json, swamp inbox prints a list instead. It shows unread messages only, unless --all is given:

●  2026-10-28  system        Your trial ends in 3 days
●  2026-10-28  direct        Thanks for the bug report
●  2026-10-28  announcement  Swamp 2026.11 is out

3 unread of 3 shown.

Each row shows the date, kind and title only. The body, link and suggested command never appear, and the list marks nothing read. When the page has another one after it, the list ends with To see older: swamp inbox --before <id>, repeating --all when it was given. With nothing unread it prints:

No unread messages. To include read ones:  swamp inbox --all

Flags

Flag Description
--all Include read messages in the list
--limit <n> How many messages to load, from 1 to 100. Default 20
--before <id> Load the page older than that message
--json Print the list as JSON. Never opens the picker

The picker always loads read and unread messages, so --all changes nothing there. --limit and --before set the page it loads.

JSON output

swamp inbox --json
{
  "status": "unread",
  "messages": [
    {
      "id": "01K8Z3M5Q7X2V9B4N6C1D8E0FA",
      "kind": "system",
      "title": "Your trial ends in 3 days",
      "createdAt": "2026-10-28T23:13:04.997Z",
      "readAt": null
    },
    {
      "id": "01K8Z3M4P6W1T8A3M5B0C7D9EZ",
      "kind": "direct",
      "title": "Thanks for the bug report",
      "createdAt": "2026-10-28T23:13:03.971Z",
      "readAt": null
    },
    {
      "id": "01K8Z3M3N5V0S7Z2K4A9B6C8DY",
      "kind": "announcement",
      "title": "Swamp 2026.11 is out",
      "createdAt": "2026-10-28T23:13:02.947Z",
      "readAt": null
    }
  ],
  "nextCursor": null,
  "dropped": 0
}
Key Description
status unread, or all with --all
messages The page, newest first. Each has id, kind, title, createdAt and readAt (null if unread)
nextCursor The id to pass to --before for the next page, or null on the last page
dropped How many messages on the page Swamp left out because they broke the inbox's format

Like the plain list, the JSON carries no body, link or suggested command, so no other text written by Swamp Club reaches an agent that runs it.

swamp inbox read

Read your newest unread message.

swamp inbox read

In a terminal

swamp inbox read opens the same picker as swamp inbox, with the newest unread message on the page highlighted, or the first row when none on the page is unread.

Outside a terminal

It prints the newest unread message and marks it read:

announcement · 2026-10-28
Swamp 2026.11 is out

A new release is ready. See the [release notes](https://swamp-club.com/feed) for what changed.

Link:  https://swamp-club.com/feed
Next:  swamp update

The message is printed as kind and date, title, the body as plain markdown, then its Link: and Next: lines when it has them. While more messages are unread, it ends with:

To read the next:  swamp inbox read

With nothing unread it prints No unread messages. and exits 0.

The message is marked read before it is printed, so a run killed in between leaves it read but unseen. The picker can still open it.

JSON output

swamp inbox read --json
{
  "message": {
    "id": "01K8Z3M4P6W1T8A3M5B0C7D9EZ",
    "kind": "direct",
    "title": "Thanks for the bug report",
    "body": "We fixed the issue you filed. Thanks for the clear reproduction.",
    "createdAt": "2026-10-28T23:13:03.971Z",
    "readAt": "2026-10-28T23:13:20.765Z"
  },
  "moreUnread": true,
  "dropped": 0
}
Key Description
message The message now read, with link and action when it has them. null when nothing is unread
moreUnread true while another unread message is waiting
dropped How many unread messages Swamp left out because they broke the inbox's format. The notice's count still includes them

readAt is the time on your machine when Swamp marked the message read.

A message body is markdown written by Swamp Club. Shown in the picker, every link in it prints as text (href) rather than as a terminal hyperlink, so you see where it really leads:

A new release is ready. See the release notes (https://swamp-club.com/feed)
for what changed.
  • A look-alike host prints as punycode, for example https://xn--swmp-club-1yh.com/….
  • A link that is not https:, or carries a username or password, prints its text followed by (link removed).
  • A bare www. or email address in running text, such as www.swamp-club.com, prints as written: its text is its whole target.

The Link: line follows the same rules: it is always an https: address with no username or password, or it is left out.

A message's Next: line suggests one Swamp command. It is only ever one of these, word for word:

  • swamp update
  • swamp quest
  • swamp inbox
  • swamp inbox read
  • swamp subscription status
  • swamp subscription start
  • swamp subscription start --collective <collective>
  • swamp extension pull <extension>
  • swamp extension search <words>
  • swamp issue get <number>

A message suggesting any other command shows no Next: line. Swamp never runs the suggested command for you; swamp inbox read --json carries it in action.command, where an agent may choose to run it.

The notice

After some commands, Swamp tells you an unread message is waiting:

ℹ A new message from Swamp Club is waiting for you.
  To read it:  swamp inbox read

With more than one unread message, the first line counts them:

ℹ 3 unread messages from Swamp Club are waiting for you.
  To read it:  swamp inbox read

Mentions and other Lab chatter never raise the notice, so its count can be lower than the list's. See Terminal inbox for which messages count.

When it shows

  • After a command that succeeded, on stderr, after the command's output.
  • Never with --json or -q.
  • Never after swamp inbox, swamp subscription, swamp auth, the long-running serve, worker, start and dashboard, or a command that needs no account.
  • Never in a Swamp run started by another Swamp run, such as a workflow step or a shell behavior. The outermost run shows it.

The notice is decided from a local cache, so any command can show it without a network request. The cache is filled by an inbox check that runs in the background during swamp workflow run, swamp behavior run, swamp extension pull and swamp extension push. See Other outbound requests for when the check runs.

When it stops

A notice stops 24 hours after it first showed, whether or not you read the message. A newer message shows a fresh notice. Reading the message, by any of the picker keys or swamp inbox read, stops it at once.

Turning it off

Set SWAMP_NO_INBOX_NOTICE=1. CI set to anything but an empty string, 0 or false does the same. Either one also stops the background inbox check. SWAMP_NO_TELEMETRY, DO_NOT_TRACK and --no-telemetry do not: the inbox check is not telemetry.

For agents

The notice's text is fixed: no message title or other text written by Swamp Club ever appears in it. --json output never carries it. Message text reaches an agent only when it runs swamp inbox read.

Local cache

The inbox check stores its answer in inbox-v2/ in the Swamp config directory, one file per API key and server, readable by you only. A file holds the unread count, the newest message's id and time, when to check next, and why checking stopped, if it did. It never holds message text, the API key or the server's address. At most 8 keys are kept.

swamp auth logout removes the file for the login it signs out. A key given only in SWAMP_API_KEY is not stored at login, so its file stays until it falls out of the 8 kept.

← PreviousIssue CommandsNext →Invite Commands