On this page
Description
The CLI can be used directly without any configuration using a java command or a user defined start script. Previously, users would normally customize their start script(s) with credentials and urls to make it easy to run actions.
Starting with CLI 8.6, it is possible to provide configuration in the form a standard property file. This is an alternative to defining unique start scripts or customizing the atlassian start script with credentials and urls. This section describes how this is done. Reference issue ACLI-691 and related.
Looking for Windows equivalent? Same configuration support works for Windows using the acli.bat start script only available with CLI 9.0 and higher. See Getting Started with Configuration for Windows
Example Configuration Property Files
The CLI distribution contains example files for both Cloud and Server.
- Go to your CLI installation directory
- Rename the example file appropriate for your environment to acli.properties
- Customize it with your credentials and urls
Cloud
- Simplest example with one site that is identified to be used by default
- Supports actions from multiple clients: jira, confluence, agile, servicedesk, and upm
- Some client actions depend on what support is licensed on the specific site
default = jiracloud -s https://examplegear.atlassian.net --user automation@examplegear.com --token xxxxxxxxxxxxxxxxxxxxxxxx
- Alternative. Also a simple example for one site but more readily able to be expanded for multiple Cloud sites sharing the same Atlassian user
# Example Cloud configuration - customize and rename this file to acli.properties
# Cloud requires an email address and a corresponding API token from Atlassian.
# Use an existing token or create one at https://id.atlassian.com/manage/api-tokens (requires an Atlassian account login).
credentials = --user automation@examplegear.com --token xxxxxxxxxxxxxxxxxxxxxxxx
cloudSite = examplegear
myjira = jiracloud -s https://${cloudSite}.atlassian.net ${credentials}
myconfluence = confluencecloud -s https://${cloudSite}.atlassian.net/wiki ${credentials}
# This defines the default client for actions, choose the most likely used client
default = ${myjira}
Server
- Simplest example with one site that is identified to be used by default
- Supports actions from multiple clients: jira, agile, servicedesk, tempo, and upm
- Some client actions depend on what support is installed and licensed on the specific site
default = jira -s http://localhost:8080 --user admin --password admin
- Simple example for accessing multiple sites
# Example Server configuration - customize and rename this file to acli.properties
credentials = --user admin --password admin
myjira = jira -s https://jira.examplegear.com ${credentials}
myconfluence = confluence -s https://confluence.examplegear.com ${credentials}
# This defines the default client for actions, choose the most likely used client
default = ${myjira}
ACLI Start Script
The CLI is a Java application and so can be called directly using the java command, however, it is usually better and recommended to use a start script which is easier to type and can be customized to make using the CLI easier. The CLI distribution has always provided some example start scripts to enable customers to construct their start script quickly. Example are scripts like jira.sh, confluence.sh, and the more general atlassian.sh. While these will still work on CLI 8.x, they are deprecated in favor of a newer approach described below that can take advantage of configuration properties.
The CLI distribution now contains another start script that support Configuration properties. The script is acli.sh and works directly or can be customized. The script will work directly provided it is run from the installation directory. For example, if the installation directory is our your path. Other scenarios can be supported with some simple modifications to the script.
#!/bin/bash
# Remember the directory path to this script file
directory=`dirname "$0"`
# Optionally customize settings like location of configuration properties, default encoding, or time zone
# To customize time zone setting, use something like: -Duser.timezone=America/New_York
# To customize configuration location, use the ACLI_CONFIG environment variable or property setting (like: -DACLI_CONFIG=...)
# If not set, default is to look for acli.properties in the installation directory
settings="-Dfile.encoding=UTF-8"
# Find the jar file in the same directory as this script
cliJar=`find $directory -name acli-*.jar`
java $settings -jar ${cliJar} "${@:1}"
Examples Using the ACLI Start Script
Cloud
cd <installation directory> ./acli.sh --action getClientInfo Client name: jiracloud, Client version: 8.8.0-SNAPSHOT, Java: Java HotSpot(TM) 64-Bit Server VM 1.8.0_161, OS: Mac OS X 10.12.6 ./acli.sh --action getServerInfo Jira version: 1001.0.0-SNAPSHOT, build: 100104, time: 6/18/19 3:00 AM, time zone: , description: Jira, url: https://examplegear.atlassian.net ./acli.sh --action getProjectList 1 projects in list "Key","Id","Name","Description","Lead","Default Assignee","Project Type","Project URL","Jira URL" "TEST","10000","Test","","Test Automation [Bob Swift Atlassian Add-ons]","","software","","https://examplegear.atlassian.net/browse/TEST" ./acli.sh --action getSpaceList "Key","Name","Description","Id","Home Page","Home Page Id","Type","Categories","URL" "TEST","Test","","98305","Test","98306","global","","https://examplegear.atlassian.net/wiki/spaces/TEST"
Server
cd <installation directory> ./acli.sh --action getClientInfo Client name: jiracloud, Client version: 8.8.0-SNAPSHOT, Java: Java HotSpot(TM) 64-Bit Server VM 1.8.0_161, OS: Mac OS X 10.12.6 ./acli.sh --action getServerInfo Product . . . . . . . . . . . : Jira Version . . . . . . . . . . . : 8.2.0 Base URL . . . . . . . . . . : https://jira.examplegear.com Title . . . . . . . . . . . . : Jira Build . . . . . . . . . . . . : 802000 Build date . . . . . . . . . : 5/20/19 12:00 AM Current time . . . . . . . . : 6/18/19 6:41 PM Time zone . . . . . . . . . . : Eastern Standard Time Connector version . . . . . . : 8.8.0 License information . . . . . : Bob Swift Atlassian Apps - Jira Command Line Interface (CLI) has a valid license. Response time (milliseconds) : 1190 ./acli.sh myconfluence --action getServerInfo Product . . . . . . . . . . . : Confluence Version . . . . . . . . . . . : 6.15.1 Base URL . . . . . . . . . . : https://confluence.examplegear.com Title . . . . . . . . . . . . : Confluence Build . . . . . . . . . . . . : 8100 Current time . . . . . . . . : 6/18/19 6:50 PM Time zone . . . . . . . . . . : Eastern Standard Time Connector version . . . . . . : 8.8.0 License information . . . . . : Bob Swift Atlassian Apps - Confluence Command Line Interface (CLI) has a valid license. Response time (milliseconds) : 1636 ./acli.sh --action getProjectList "Key","Id","Name","Description","Lead","Default Assignee","Project Type","Project URL","Jira URL" "TEST","10000","Test","Example","automation","","software","","https://examplegear.atlassian.net/browse/TEST" ./acli.sh myconfluence --action getSpaceList "Key","Name","Description","Id","Home Page","Home Page Id","Type","Categories","URL" "TEST","Test","","98305","Test","98306","global","","https://confluence.examplegear.com/display/EXPERIMENT"
Tips
Recommendations
While you can run the script directly from the installation directory as the following examples show, we recommend putting the directory on your path. Also copy or rename the shipped file to acli for easier typing. You can also use -a instead of --action to speed typing.
With these recommendations, the example becomes:
acli -a getServerInfo
Getting Action Help
Help is available for any action directly from the command line. Online references are available for all clients: Action Reference.
acli -a getProjectList --help
getProjectList - List defined projects with optional filtering by lead, category, and regex on project key. Get projects with no category by setting the category parameter to blank.
Optional parameters . . : lead, category, regex, outputFormat, file, columns, encoding
Output formats . . . . : 1 - default, 2 - issue count and category, 999 - all
Advanced Enterprise Features
For companies with larger numbers of Cloud and Server instances that need to be accessed, the configuration support a number of features that enables enterprises level configuration and shared or centralized configurations.
- Variables - use variables to minimize duplication and ease maintenance
- Includes - include other configuration property files to allow shared configurations with user customized credentials or private server configurations
- Regular expression search - use regular expressions to match instance name patterns to a configuration to enable dynamic recognition of new sites and minimize configuration
- Shared configuration - file configuration can be easily shared via shared directories or repositories (important for CI build environments)
## Shared CLI configuration properties - order is important. First exact match wins, then first regex match wins.
## Put customized credentials and entries in your user home directory acli-private.properties file
include = ~/acli-private.properties
## Appfire Cloud sites
ban = jiracloud -s https://bobswift.atlassian.net ${credentials.cloud}
wan = jiracloud -s https://wittified.atlassian.net ${credentials.cloud}
fan = jiracloud -s https://feedthree.atlassian.net ${credentials.cloud}
## Other Cloud sites you may have access to like ecosystem.atlassian.com
([a-z0-9]+.atlassian.net) = jiracloud -s https://$1 ${credentials.cloud}
## Server sites
((?:jira)|(?:confluence)|(?:bamboo)|(?:bitbucket)) = $1 -s https://$1.examplegear.com ${credentials.server}
(.*).examplegear.com = -s https://$1.examplegear.com ${credentials.server}
# This defines the default client for actions, choose the most likely used configuration
default = ${ban}
Example Include For User Level Configuration
## My credentials for both cloud and server access. Cloud access needs an Atlassian API token - https://id.atlassian.com/manage/api-tokens
credentials.cloud = --user ${my.email} --token ${my.token}
credentials.server = --user ${my.user} --password ${my.password}
my.email = ...@...
my.user = ...
my.password = ***
my.token = ************************
## My local installs
jiralocal = jira -s http://localhost:8080 --user admin --password admin
confluencelocal = confluence -s http://localhost:8090 --user admin --password admin
