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
- Open any terminal
- Type in 'swamp help'
- 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 }, [...]
Closed
No activity in this phase yet.
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(orswamp -h, or plainswamp) for the top-level command listswamp <command> --helpfor 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.