General Usage

There are hundreds of commands in this CLI. Most of them share common patterns and you don’t need to learn new parameters or arguments for each of them.

Arguments vs Flags

Flags are in the form like --flag (long form) or -f (short form). Not all flags have a short form especially a command is taking lots of flags. Arguments does not use a prefix with ‘--’ or '-'. Usage of arguments is limited because they are not named and may cause confusion. Order of them on the command line is important. Order of flags are not important because they are named. We only use arguments if a command accepts a single parameter (argument/flag) or we need to consume a large JSON input (like when creating an issue). In all cases arguments are optional and there is always a flag equivalent.

Example:

First command above uses an argument to specify an issue. The second command uses a flag to specify an issue.

Repeated Flags

Sometimes a flag can be repeated multiple times. Both of following examples are valid and do the same thing.

Boolean Flags

Boolean flags have usually a default value and you don’t need to specify it when it has a default value. Yes no for boolean flags are specified with ‘--no’ prefix.

Date Flags

Most of the time Date Flags/Arguments can be specified in two ways. Following examples specifies the same instant in time.

• UNIX timestamp in milliseconds. Example: 1524815284277

• ISO 8601 string format (YYYY-MM-DDThh:mm:ss.sTZD). Example: 2018-04-27T07:48:04.000+0200, 2018-04-27T07:48:04.00-0230

The part specified with + is timezone information. The part specified with . is milliseconds part.

Help

You can use ‘--help' to see all available arguments and flags for a command.

Command Grouping

Commands are grouped to make them easy to remember. For example all of project related commands are grouped under ‘project’ command an you can see the list of sub-commands using ‘--help’ parameter on parent command.

To list of all parent commands:

To list all sub-commands of a parent command:

If you want to see details of a sub-command you can use ‘--help’ on subcommand level.

Output

Default output format for CLI is tabular. In addition to tabular format you can also use json and yaml output. json and yaml format always outputs the same information but in different format but for tabular output CLI may sometimes output a slightly different/missing information.

You can specify which format you want using a flag. --output=json switches to JSON and --output=yaml switches to YAML format. Since tabular output is default there is no flag for it, just don’t specify any output flag. When using tabular format you can also use 2 other flags to modify output.

--no-truncate will disable truncation of output. If there are a lot of columns, a tabular output may not fit to width of the terminal. In this case it will truncate content and header of some columns to fit whole output to width of the screen. If you don’t want this, you can specify --not-truncate option.

--extended may show extra columns which are normal hidden. Since there may be a lot of information to fit the width of the screen by default some commands may not show all the columns by default. For example nearly all tables includes a ‘self’ column which contains URL of the entity. This is very long and occupies a lot fo space on the screen and may cause lots of columns to be truncated. For this reason ‘self’ column and some other columns are hidden by default. You can specify --extended flag to show these columns.

Here is our general recommendations on when to use which output format:

table: This is the default format and suitable for human eyes especially if all the columns of output fits to width of the terminal and there are multiple rows of data. For example when getting list of users.

yaml: Prefer this format when there are a lot of columns and it is difficult to fit all columns on the screen. Especially when displaying a single row of information.

json: Prefer this format when writing integrations and scripts. It is suitable for hierarchical data too.

Issue ID or Key

Most commands that expects an issue can either accepts an issue ID or key. In that case this flag is usually ‘issue’ and you can use either ‘--issue=10000’ or ‘--issue=TEST-1’ to specify issue. If a command explicitly needs issue ID the flag will be ‘issueId’ and if a command explicitly needs issue key, the flag will be ‘issueKey’.

Account ID or Username

For Jira Cloud usage of username is deprecated and removed from most of Atlassian’s API due to GDPR concerns. Most of Cloud APIs are now using ‘Account Id’ instead of ‘Username’. For Server and DC products there is no AccountId but there are ‘user key’ and ‘username’. ‘User key’ is like ‘Account Id’ and does not reveal any personally identifiable information about the user. Username is usually very similar to real name of the user. Nearly all of Server/DC APIs uses username.

For most commands you can use ‘user’ flag to specify user, either using accountId like ‘--user=5544:34343:325342:1232’, or using username like ‘--user=admin’. Some commands when running for Cloud explicitly expects account Id and in this case you need to use ‘--accountId’ flag. Correspondingly for Server/DC you can use ‘--username=admin’.

Target Site and Aliases

All commands accepts ‘--site’ flag to specify the alias of a Jira site as the target of a command. You can run commands on multiple sites by using ‘site’ flag. In order to use a site you need to add it using ‘jira config:add’ command. If you don’t specify a site when running a command it will use default site specified previously using ‘jira config:set-default’ command.

Running Commands as Another User

When adding a site to CLI, you provide an Atlassian account credentials or username for running commands. Normally all commands run as this user but sometimes you may want to run a command as another user. Some Jira APIs doesn’t allow a to specify a user for an action but some APIs allow a user to be specified. For example when adding a ‘Vote’ for an issue, you can’t specify which user voting so it always uses the user you have specified when adding the site. But when adding a ‘Watcher’ for an issue, API allows you to specify a user as watcher so you can make another user watch the issue other than the user you specify when configuring the site. Very similarly you can’t specify a user when adding a comment to an issue or when logging work to an issue.

For Cloud there is nothing we can do about it. For Server and DC you can mitigate this by specifying ‘runAs’ parameter to any command. Of course this requires 'Jira Administrators' or 'Jira System Administrator' global permission.