[Domantas]

PR 1 of 3 for "Agent-native CLI" (docs/tasks/agent-native-cli.md). PR 2 (feat/agent-native-cli-2, discovery + dry-run everywhere) and PR 3 (feat/agent-native-cli-3, startup + agent docs + norbix ai init) are stacked on top of this branch so each stays reviewable; merge this one first.

Breaking: destructive commands (delete, stop, regenerate, block, disable, db update --many, db delete --id) now exit 3 and send nothing when there is no terminal and no --yes — before, norbix users delete x </dev/null (or | tee) deleted silently. users block, scheduler disable, payments disable, webhooks disable, push integration disable ask for confirmation now. Error text moved to stderr as Error: … / Hint: …; exit codes are the documented 0–9 table instead of oclif's 1/2.

What changed

• Exit codes (src/lib/exit-codes.ts): the documented table 0–9, the same with and without --json. No oclif import — the MCP server can share it.
• One error envelope (src/lib/cli-error.ts, BaseCommand.catch): every failure — SDK errors, parser errors, bad JSON input, prompts, bugs, unknown commands — becomes {"error": {code, message, status, exit, fieldErrors, url, traceId, hint, docs}} on stdout with --json, or Error: … / Hint: … on stderr. oclif's own JSON error path (the 22 000-line parse-context dump) never runs. Unknown commands go through a command_not_found hook. No oclif import in the lib either.
• Confirmation without a terminal (BaseCommand.confirmOrFail): destructive commands ask in a terminal as before; in a non-interactive shell (stdout or stdin not a TTY, CI set, or --json) they exit 3 with a one-line message naming --yes, and the request is never sent. "No" at the prompt exits 9 instead of printing Cancelled. and exiting 0.
• --dry-run on every destructive command and on hub/api: the SDK builds the request with the real auth, region and project; a transport middleware stops it just before fetch; the SDK call and the HTTP request (method, URL, headers with the token redacted, body) are printed; exit 0. A dry run with a missing region or key fails like the real call would.
• login / configure: every prompt guarded; non-interactive → exit 2 with the three flag/env alternatives, no stack trace, no unsettled-await warning.
• No ANSI codes with --json, NO_COLOR or a pipe (init hook; there is still no colour library).
• README: new "Errors and exit codes" section.

Tests

tests/agent-mode.test.ts runs the built CLI as a child process (pipes everywhere, like an agent sees it) against a fake gateway on a free port: every destructive command exits 3 without --yes and sends nothing, and runs with --yes; --dry-run prints the call and sends nothing; the envelope and exit code for 404 / 400 with fieldErrors / 401 / 500 / network / usage / unknown command / bad JSON input / unknown profile / login without a terminal — same exit code with and without --json, stdout one JSON document, stderr empty. tests/cli-error.test.ts unit-tests the mapping. 165 tests green.

Reproduction (the §6 harness, after)

users delete abc123 --profile x                        exit=3 stdout_lines=0   (nothing sent)
db update orders --many ... --profile x                 exit=3 stdout_lines=0   (nothing sent)
users get missing --profile x --json                    exit=5 stdout_lines=12  (status, code, traceId, hint)
users get bad --profile x --json                        exit=6 stdout_lines=16  (fieldErrors.email)
users list --profile y --json                           exit=7 stdout_lines=10  (url)
db update orders --profile x --json                     exit=2 stdout_lines=9   (was 26 879 lines)
nothing --json                                          exit=2 stdout_lines=9   (envelope)
users delete abc123 --profile x --dry-run --json        exit=0 stdout_lines=17  (request shown, nothing sent)

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 1.6.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀