[jira] [Updated] (CAMEL-25388) camel-jbang - Make the Camel CLI reliable for AI agents and scripts (exit codes, stderr, JSON, timeouts)

["Claus Ibsen (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/CAMEL-25388?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Claus Ibsen updated CAMEL-25388:
--------------------------------
    Attachment: 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)