Repository navigation
--mode agent does not format early errors as JSON #559
Description
What happens
In agent mode the CLI prints errors as JSON, so an AI agent can read the error code. Agent mode can be turned on with the --mode agent flag or the CLERK_MODE=agent environment variable. The flag takes effect only once a command starts running, so errors that happen before that are printed as plain text in a terminal, even with --mode agent. The environment variable takes effect from the start.
There are two groups of early errors:
- Errors from
--input-json(invalid JSON, a missing file, a value that isn't an object). With--mode agentthey print as plain text. WithCLERK_MODE=agentthey print as JSON. - Errors from the command-line parser itself (unknown command, unknown option, missing argument, invalid choice). These print as plain text with either setting, because the parser prints them and exits without going through the CLI's error handler.
Observed, in a terminal:
$ clerk --mode agent --input-json { whoami
error: Invalid JSON in --input-json. Please provide valid JSON.
$ CLERK_MODE=agent clerk --input-json { whoami
{"error":{"code":"invalid_json","message":"Invalid JSON in --input-json. Please provide valid JSON."}}
$ clerk --mode agent nosuchcommand
error: unknown command 'nosuchcommand'
$ CLERK_MODE=agent clerk nosuchcommand
error: unknown command 'nosuchcommand'
Who hits it
An agent or script that passes --mode agent while running the CLI in a terminal (for example an agent tool that allocates a terminal), and makes a mistake in its arguments or --input-json. When stdout isn't a terminal, the CLI already defaults to agent mode, so the --input-json errors in group 1 print as JSON there. The parser errors in group 2 print as plain text either way.
What the person experiences
The agent receives a plain-text error where it expects JSON with a code. It can usually still read the message, but code that parses the JSON error fails.
How big a deal it is
- How often: low. It needs a malformed command, and for group 1 also a terminal with the flag instead of the environment variable.
- How bad when it happens: low. The message is still readable. Only automated handling of the error code breaks.
- Does it block them: no.
Proposed fix
- Apply
--modebefore anything else runs: read it from the raw arguments at startup, before--input-jsonis expanded, instead of in the command hook. - Route the parser's own errors through the CLI's error handler (for example with Commander's
exitOverride), so they get a code and follow the mode like other errors.
Where it goes: runProgram and the preAction hook in packages/cli-core/src/cli-program.ts, and packages/cli-core/src/mode.ts.
Tests
--mode agentwith invalid--input-json, in a terminal, prints the JSON error.- An unknown command with
--mode agent, or withCLERK_MODE=agent, prints a JSON error with a code. - Without either setting, in a terminal, both still print plain text.
Activity