[
https://issues.apache.org/jira/browse/CAMEL-25388?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-25388:
--------------------------------
Attachment: (was: camel-cli-agent-readiness-analysis.md)
> 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
> Priority: Major
> 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)
