sutram Errors that help agents
An agent reads your error message and decides what to do next. A good one leads to one corrected command. A vague one leads to guessing, or to starting over.
What Sutram does for you
| Mistake | Exit | Message comes from |
|---|---|---|
| Unknown command | 127 | Sutram, with "did you mean" when a name is close |
| Unknown option or argument, wrong type, missing required input, a value outside the schema's limits | 2 | Sutram, from the input schema (what is checked) |
| Needs approval it did not get | 130 | Sutram, with the question to ask |
Anything your run() throws | 1, or the code of a CommandError | You |
So the schema is your first error message. A minimum, an enum, a maxLength, a pattern or a required turns into a precise usage error without a line of code. It ends with where the usage is: form get: field is required. Try form get -h.
Writing your own
Throw a CommandError with a message and an exit code:
throw new CommandError(
`${base} set: "${s}" is not a valid invoice number. ` +
"Use INV- and at least four digits, such as INV-20417.",
EXIT.USAGE,
);A good message:
- Starts with the command, so a failed line in a batch is obvious.
- Says what is wrong with this input, not in general.
- Says what would work: the format, the allowed values, an example.
- Names the next command when there is one: "Set it first, for example:
form set request email …". - Lists everything at once. "email, summary and phone are required" saves two round trips over naming one at a time.
Use EXIT.USAGE (2) when the input was wrong, and EXIT.FAILED (1) when the input was fine but it did not work, including when the thing it names (a form, a list, a menu) is not on the page. EXIT.NOT_FOUND (127) belongs to the clients: it means the command itself does not exist.
Hints on success, too
Results guide agents as much as errors do:
- "The cart is empty. Try shop list, then cart add."
- "topic set. The form now also asks for: invoice, amount."
- "Saving. The page reloads; then status shows where it went."
Batches stop at the first failure
A pasted block, a multi-line entry and sutram_batch stop at the first command that fails, and the console says which line. Earlier commands keep their effect unless the provider has batch hooks. So the agent's correction is the failed line and the ones after it.