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:
jira issue:vote ERP-53
jira issue:vote --issue=ERP-53
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.
jira worklog:get-worklogs --worklogId=18900 --worklogId=18901 --worklogId=18902
jira worklog:get-worklogs --worklogId=18900 18901 18902
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.
--notifyUsers --no-notifyUser
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:
jira --help
To list all sub-commands of a parent command:
jira project --help
If you want to see details of a sub-command you can use ‘--help’ on subcommand level.
jira project:create --help
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.
jira project:get-all Id Key Name Project Type Key Archived 10001 ACN Accurate Notebook software false 10005 ADS Adaptable Summer software false 10008 AUC Auxiliary Card software false 10006 CLG Clean Guardian software false 10004 COI Compressing Interface software false
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.
jira server-info:get --output=yaml baseUrl: 'http://localhost:8080' version: 8.14.0 versionNumbers: - 8 - 14 - 0 deploymentType: Server buildNumber: 814001 buildDate: '2020-11-23T00:00:00.000+0300' databaseBuildNumber: 814001 serverTime: '2021-01-06T12:36:45.790+0300' scmInfo: ab08d3d2b500818bdad5c85d636b509d4cade801 serverTitle: Jira Server
json: Prefer this format when writing integrations and scripts. It is suitable for hierarchical data too.
jira issue:get ERP-53 --output=json
{
"expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
"id": "12705",
"self": "http://localhost:8080/rest/api/2/issue/12705",
"key": "ERP-53",
"fields": {
"issuetype": {
"self": "http://localhost:8080/rest/api/2/issuetype/10000",
"id": "10000",
"description": "Created by Jira Software - do not edit or delete. Issue type for a big user story that needs to be broken down.",
"iconUrl": "http://localhost:8080/images/icons/issuetypes/epic.svg",
"name": "Epic",
"subtask": false
},
"timespent": 21600,
"project": {
"self": "http://localhost:8080/rest/api/2/project/10000",
"id": "10000",
"key": "ERP",
"name": "Enterprise Resource Planning",
"projectTypeKey": "software",
"avatarUrls": {
"48x48": "http://localhost:8080/secure/projectavatar?pid=10000&avatarId=10203",
"24x24": "http://localhost:8080/secure/projectavatar?size=small&pid=10000&avatarId=10203",
"16x16": "http://localhost:8080/secure/projectavatar?size=xsmall&pid=10000&avatarId=10203",
"32x32": "http://localhost:8080/secure/projectavatar?size=medium&pid=10000&avatarId=10203"
}
},
"fixVersions": [],
......
}
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.
yarn jira issue:vote TEST-7 //adds a vote for the user specified when configuring site (usually admin) yarn jira issue:vote TEST-7 --runAs=walterwhite //ads a vote for the user walterwhite