Skip to content

Commit 7e681bf

Browse files
razor-xclaude
andauthored
feat: Make CLI output machine-readable and pipeable (#588)
Replace ad hoc console.log calls with an injectable Output so the CLI has one place that decides what goes where, and so output can be asserted in tests with an in-memory implementation. - Only command results go to stdout: prompts, spinners, progress, and other information are written to stderr. - Add --json to read request params from stdin and write the response as JSON. The JSON format is used automatically when stdout is not a terminal, and --no-json opts out. - Support unix pipes end to end: params may be piped or redirected in, and the response piped or redirected out. - Trim responses to the response key and pagination, using the response key from the API blueprint. - Exit non-zero on a failed request or an error. Claude-Session: https://claude.ai/code/session_01NKsb8oTieozDEGJtiwWqBo Co-authored-by: Claude <noreply@anthropic.com>
1 parent e31c80c commit 7e681bf

33 files changed

Lines changed: 1101 additions & 151 deletions

README.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,64 @@ seam access-codes create --code "1234" --name "My Code"
9797
seam access-codes list --device-id $MY_DOOR
9898
```
9999
100+
### Output
101+
102+
Only the response is written to stdout, so any command may be piped or
103+
redirected. Prompts, progress, and other information are written to stderr.
104+
105+
The response is trimmed to the response key and pagination: no other top level
106+
fields are reported.
107+
108+
```bash
109+
# The response, and nothing else, ends up in the file
110+
seam devices list > devices.json
111+
112+
# Prompts and progress still show up in the terminal
113+
seam devices list | jq '.devices[].device_id'
114+
```
115+
116+
### JSON
117+
118+
Request params may be piped or redirected in as a JSON object. Params given as
119+
arguments win over params read from stdin.
120+
121+
```bash
122+
# Read params from a file
123+
seam locks unlock-door < params.json
124+
125+
# Or from another program
126+
echo '{"device_id": "'"$MY_DOOR"'"}' | seam locks unlock-door
127+
128+
# --device-id wins over any device_id in params.json
129+
seam devices list --limit 5 < params.json
130+
```
131+
132+
Pass `--json` to write the response as JSON. It is enabled automatically
133+
whenever stdout is not a terminal, so piping and redirecting produce JSON
134+
without passing anything. Pass `--no-json` to opt out and get the pretty
135+
format instead.
136+
137+
```bash
138+
# Both write JSON
139+
seam devices list --json
140+
seam devices list | jq
141+
142+
# Pretty printed, even though it is piped
143+
seam devices list --no-json | less
144+
```
145+
146+
Without a terminal to prompt on, the CLI behaves as though
147+
`--non-interactive` was given: rather than waiting for an answer nobody can
148+
give, it exits with an error naming what is missing.
149+
150+
```bash
151+
$ echo '{}' | seam locks unlock-door
152+
Missing required parameter for /locks/unlock_door: --device-id
153+
```
154+
155+
An error exits non-zero. A request that fails reports its `error` on stdout,
156+
so it can be inspected from a pipe; anything else is written to stderr only.
157+
100158
## Development and Testing
101159
102160
### Quickstart

package-lock.json

Lines changed: 0 additions & 42 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)