How to get started with Atlasian CLI

Prerequisites

There are two ways to authenticate with Atlassian CLI:

• API token
• OAuth

Authentication using API token

1. Generate an API token from your Atlassian account
2. Run either of the following commands to authenticate with Atlassian CLI:

Read token:

1
2
$ echo <token> | acli auth login --site "mysite.atlassian.net" --email "user@atlassian.com" --token

Read token from file:

1
2
acli auth login --site "mysite.atlassian.net" --email "user@atlassian.com" --token < token.txt

Authentication using OAuth

1. Run the following command to authenticate with Atlassian CLI:

1
2
acli auth login --web

2. Your web browser will launch, prompting you to choose a site for authentication. Once you click Accept, a success message will appear in the browser. You can then close the tab and go back to the terminal to finish the authentication by selecting a site.
   You must select the same site in the terminal that you selected in the web browser.

Command structure

The CLI command may use the following structure:

1. <COMMAND> signifies an Atlassian product, such as Jira (jira).

2. <SUBCOMMAND-1> indicates a feature or entity associated with the relevant product, such as a work item.

3. <SUBCOMMAND-2> describes the action to be executed on the <SUBCOMMAND-1>, including options like create, update, or delete.

4. [FLAGS] represent optional parameters that dictate how the action will be carried out. If omitted, default values will be utilized.

The acli tool operates using a structured command-line syntax that requires a specific sequence for execution.

• To use acli, start by invoking the command followed by the primary command <COMMAND>. You can include optional nested subcommands if needed.
• Optional flags or arguments are indicated by enclosing them in square brackets, for example, [FLAGS].

1
2
$ acli <COMMAND> [<SUBCOMMAND> ...] {MANDATORY FLAGS} [OPTIONAL FLAGS]

Some Useful commands

Create a work item

$ acli jira workitem create

1
2
$ acli jira workitem create -p TEST -i Bug -s 'Bug or feature'
# Example output for an interactive workitem creation. 
✓ Workitem TEST-123 created: example.atlassian.com/browse/TEST-123 
$ acli jira workitem create TEST -i bug --generate-required-fields-json > new_workitem.json
# edit the provided template
# ... 
$ acli jira workitem create TEST -i bug < new_workitem.json
✓ Workitem TEST-123 created: example.atlassian.com/browse/TEST-123 

Assign a work item

$ acli jira workitem assignee

1
2
$ acli jira workitem assignee TEST-123 --user unassigned
✓ TEST-123 successfully unassigned
$ acli jira workitem assignee TEST-123 --user me
✓ TEST-123 successfully assigned to Example User
$ acli jira workitem assignee TEST-123 --user '5b10ac8d82e05b22cc7d4ef5'
✓ TEST-123 successfully assigned to Example User
$ acli jira workitem assignee TEST-123 --user 'user@example.com'
✓ TEST-123 successfully assigned to Example User

Transition a work item

1
2
$ acli jira workitem transition TEST-123 --next done
# Example output
✓ Workitem TEST-123 is resolved as 'Done'