How to create Jira comments with ADF formatting using acli?

Question

I'm trying to create formatted Jira comments using the Atlassian CLI (acli) with Atlassian Document Format (ADF), but I'm having trouble getting the formatting to render correctly.

What Works:
The acli jira workitem comment update command correctly supports --body-adf for updating comments with ADF formatting:

acli jira workitem comment update --key "TICKET-123" --id 12345 --body-adf /path/to/comment.adf.json

This renders bold, italic, lists, and other formatting perfectly in Jira.

Note: The --body-adf flag is documented here: https://developer.atlassian.com/cloud/acli/reference/commands/jira-workitem-comment-update/#options but doesn't appear in the --help output for the command.

What Doesn't Work:
I cannot figure out how to CREATE a new comment with ADF formatting. I've tried:

1. Using --body with ADF JSON:
acli jira workitem comment create -k "TICKET-123" --body '{"version":1,"type":"doc","content":[...]}'
Result: The raw JSON is posted as plain text

2. Using --body-file with an ADF JSON file:
acli jira workitem comment create -k "TICKET-123" --body-file comment.adf.json
Result: Comment is created but formatting doesn't render (shows as plain text)

3. The comment create command doesn't have a --body-adf flag (at least not in the help menu)

My Question:
How can I create a NEW comment with ADF formatting using acli? Is there a --body-adf flag for comment create that's not documented in the help menu? Or is there a different approach I should be using?

The ADF structure I'm using matches what Jira stores when I manually format comments in the UI (verified via the Jira REST API), so I believe the ADF format itself is correct.

Any guidance would be appreciated!

Thanks!

unknown · Answer

Yep, The v3 REST API uses ADF exclusively for formatting rich text fields, whereas the v2 REST API uses markdown... but since both versions of the API are still happily evolving side-by-side, you're safe to keep using all the v2 endpoints until Atlassian says otherwise.

With regards converting to and from ADF, there are a few third party libraries that do a good job, but still nothing 100% perfect or 'official' from Atlassian yet other than a JavaScript based framework in the @atlaskit. Refer to JRACLOUD-77436

Ryan Snyder_b1f3xm · Answer

Thank you! I thought it was user error. Very frustrating! I'll use the REST API.

I thought I remember reading something about v3 of the API not being able to take in markdown and that v2 would have to be used if you want to provide markdown. Will I also have to convert MD to ADF for v3?

unknown · Answer

Howdy @Ryan Snyder

Welcome to the infuriating world of the Atlassian Command Line Interface!

Yep. When you provide what you know is correctly formatted ADF (because it renders correctly when submitted via the REST API and renders in the ADF Document Viewer tool) in a *.json file via the --body-file option to the jira workitem comment create command, the resulting comment will indeed contain a mish-mash of some ADF nodes and marks being parsed and rendered correctly, others ignored and rendered as plain text, with others causing InvalidPayloadException errors at the command line.

Yep. There is no --body-adf option or similar, like the comment update command has, to 'tell' the comment create command to know what to expect. Why one command has a specific option and the other doesn't... who knows!!

I spent ages playing around with the ACLI months ago and found too many things like this that were only half-baked or vaguely documented to consider using it for anything serious at this point in time.

If you are a half competent programmer, I recommend that you stick with interacting with Jira's REST API, as it's much more reliable and well documented, plus has WAAAY more functionality than what the ACLI can currently provide.