Claus Ibsen created CAMEL-25388:
-----------------------------------
Summary: camel-jbang - Make the Camel CLI reliable for AI agents
and scripts (exit codes, stderr, JSON, timeouts)
Key: CAMEL-25388
URL: https://issues.apache.org/jira/browse/CAMEL-25388
Project: Camel
Issue Type: Improvement
Components: camel-jbang
Reporter: Claus Ibsen
Assignee: Claus Ibsen
Fix For: 4.24.0
Attachments: camel-cli-agent-readiness-analysis.md
The Camel CLI is increasingly driven by AI agents, MCP tools, the TUI and
scripts. Today many commands exit 0 when they fail (no matching integration,
timeout waiting for the running integration, action rejected by the
integration), print errors to stdout (which corrupts {{--json}} output), and
hang forever without a TTY ({{--watch}}, {{log}}, {{receive}}, ...). Callers
work around this by scraping log/console text.
This umbrella makes the CLI reliable and machine-friendly.
h3. Agreed contract
||Exit code||Meaning||
|0|Success|
|1|Command ran, outcome negative (validation errors, doctor check failed,
integration rejected the action)|
|2|Usage error (picocli), or interactive-only command without a TTY|
|3|Not found: no matching integration/route/component/service, or ambiguous
match (message lists the matches)|
|4|Timeout: no reply from integration, background run still starting, process
did not stop|
|70|Internal error: unexpected exception (stack trace on stderr)|
|n|Child exit code passed through (run via mvn/jbang/java)|
* stdout carries data only; errors, warnings, tips and banners go to stderr.
* With {{--json}} stdout is exactly one JSON document: {{[]}} when empty,
{{\{"status":"error","code":N,"message":"..."\}}} on error (plus the same exit
code).
* No command blocks on stdin without a TTY.
* Behaviour changes are documented in the 4.24 upgrade guide.
h3. Root causes
* No central exception/exit-code mapping in {{CamelJBangMain}}.
* {{Printer.printErr}} writes to stdout.
* {{FileCliConnectorTransport}} drops action errors (the WebSocket transport
handles them).
* CLI uses the legacy shared {{<pid>-action.json}} file; timeouts return null
and exit 0.
* "No match" is not an error; numeric pids are trusted without a Camel status
file.
* Watch/follow loops only stop on a console line, so they never end without a
TTY.
* {{findPids}} exists in 6 diverged copies.
The sub-tasks are ordered; tech-debt work comes after the behaviour work.
_Claude Code on behalf of davsclaus (Claus Ibsen)_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
