Scripting

With --json, stdout holds only JSON, indented by two spaces, while notes and progress stay on stderr, and nothing prompts. A list prints one { items, hasMore, nextCursor } document, with --all too, on a terminal or in a pipe, and hasMore is true when --max stopped it. The few lists with a shape of their own, such as addresses list, say so in their help. An API object prints as the API returned it, and a hand-written command prints the object its help describes.

nextmail whoami --json | jq -r .workspaceIdnextmail emails list --status failed --json | jq -r ".items[].id"

An error goes to stderr as one line of JSON, and the exit code is the one a person would get:

{"error":{"type":"permission_error","code":"insufficient_scope","message":"This API key does not have the \"domains:write\" scope.","hint":null,"next":"Use an API key that has domains:write.","status":403,"requestId":"req_7Hc2kQ","param":null,"docUrl":"https://nextmail.sh/docs/api/errors#insufficient_scope","exitCode":4}}

Some output is a stream of JSON objects, one per line, so a pipeline can handle each item as it arrives:

• —A resource list with --all piped without --json, or with --ndjson. --max <n> stops after that many items.
• —nextmail temp watch --json, one line per new message.
• —nextmail mcp serve, one JSON-RPC message per line in each direction.

nextmail contacts list --all > contacts.ndjsonnextmail emails list --status failed --all --max 500 | jq -r .id

The CLI prompts only when stdin and stdout are both terminals, and none of --json, --no-input or CI applies. Otherwise:

• —A missing required value stops with exit code 2 and names the flag to pass.
• —A destructive command stops with Refusing to run unattended. Pass --yes to confirm. and exit code 2, unless you pass --yes.
• —A change that needs a verification code stops with exit code 4, because nobody can type it. Use an API key, or run nextmail verify first.
• —A browser sign-in stops with exit code 2 before anything is registered, so sign in with nextmail login --with-token or NEXTMAIL_API_KEY instead.

Give the job an API key with only the scopes it needs, keep it in a secret, and let NEXTMAIL_API_KEY carry it. Nothing is saved, nothing prompts, and no update check runs.

- name: Tell the team  env:    NEXTMAIL_API_KEY: ${{ secrets.NEXTMAIL_API_KEY }}  run: |    npx -y @nextmail/cli@0.0.1 send \      --from deploys@acme.com \      --to team@acme.com \      --subject "Deployed ${{ github.sha }}" \      --text "Build ${{ github.run_number }} is live." \      --idempotency-key "deploy-${{ github.run_id }}"

ADDRESS=$(npx -y @nextmail/cli@0.0.1 temp new --ttl 15)./signup-test.sh "$ADDRESS"npx -y @nextmail/cli@0.0.1 temp watch --first --json | jq -r .snippetnpx -y @nextmail/cli@0.0.1 temp delete --yes

failed=$(nextmail emails list --status failed --json | jq ".items | length")test "$failed" -eq 0