Skip to main content
← Back to list
01Issue
BugClosedSwamp CLIPublic
Assigneeszack

Relationships

#4648 swamp help outputs in json instead of text

Opened by ericsherrill · 11/11/2026

Description

The CLI command 'swamp help' is outputting JSON instead of human-readable text in the terminal. Expected to see same nicely formatted help output as bare 'swamp' or 'swamp -h' commands, or, at worst, an error message / syntax reminder.

Steps to Reproduce

  1. Open any terminal
  2. Type in 'swamp help'
  3. Observe JSON formatted output

Environment

  • swamp version: 20261024.002231.0-sha.9b1288d1
  • OS: windows
  • Shell: C:\Program Files\Git\usr\bin\bash.exe

Additional Context

FYI 'swamp --help' works as expected also. Would be nice though if 'swamp help' was smarter.

Example:

$ swamp help { "version": "20261024.002231.0-sha.9b1288d1", "root": { "name": "swamp", "aliases": [], "description": "AI Native Automation CLI\n\nWith --json, a command that fails writes its error to stderr as one JSON\ndocument:\n\n { "error": "", "code": "" }\n\nMatch on "code" when it is present (an error without a stable identifier\nhas none, and other fields may appear); the message text can change\nbetween releases.\n\nExit codes, shared by every command:\n\n 0 success\n 1 error\n 2 unknown command or subcommand, or too many arguments\n 75 temporary failure, such as lock contention or a temporary sign-in\n block; retry with backoff\n 130 interrupted (Ctrl+C)\n\nA command that adds codes of its own lists them in its help.", "hidden": false, "arguments": [], "options": [ { "flags": "--json", "description": "Output in JSON format (non-interactive)", "required": false, "collect": false, "takesValue": false, "hidden": false }, [...]

02Bog Flow
✓OPEN✓TRIAGED○IN PROGRESS◉CLOSED+ 1 MOREASSIGNEDCLASSIFICATION

Closed

11/11/2026, 5:30:27 PM

No activity in this phase yet.

03Sludge Pulse
zack assigned zack11/11/2026, 5:21:38 PM
Editable. Press Enter to edit.

zack commented 11/11/2026, 5:27:41 PM

Thanks for the report, and for the clear repro.

The JSON output is intentional. swamp help is a hidden command made for AI agents: it prints the full CLI schema (every command, argument and option) as structured JSON so an agent can check exact flags before it runs a command. The skills swamp installs tell agents to run swamp help <command>, so changing its default output would break them.

For human-readable help, use the standard flags, which print formatted text:

  • swamp --help (or swamp -h, or plain swamp) for the top-level command list
  • swamp <command> --help for a specific command, e.g. swamp behavior run --help

The repo-init output and the getting-started text already point to swamp --help. We are keeping swamp help as it is for now. Thanks again for flagging how confusing the name is to someone typing it by habit.

zack commented 11/11/2026, 5:30:27 PM

Closing as working as intended. Use swamp --help for human-readable help.

ericsherrill commented 11/11/2026, 5:32:35 PM

Fair enough, thanks for the clear explanations.

Sign in to post a ripple.