Tips

The Atlassian Command Line Interface (CLI) helps you automate tasks and streamline business processes across Atlassian products. Each CLI distribution includes multiple product-specific clients, each with its own set of actions. All clients support consistent interfaces, protocols, and implementations, and come with built-in help documentation accessible via --help or by running the default command.

This guide covers general usage tips, explains how to use common and special parameters, and offers platform-specific quoting rules. It also details how to avoid common pitfalls with special characters and encoding requirements.

1. Common parameters

The following parameters are available across most CLI actions, even if not explicitly listed:

--help
--verbose
--debug
--quiet
--special
--dateFormat, --dateFormat2
--outputType

For database-related actions such as get*List, you can also use these optional parameters:

--url, --dbUser, --dbPassword, --database
--driver, --dbJar, --host, --port
--dbCreateTable, --dbTable, --dbTableKeys
--afterSql, --propertyFile

Some parameters are required based on the action being performed. Refer to the action-specific help (--action <name> --help) for details.

2. General tips for using parameters

To get help for a specific action, type the action followed by --help.
Example:
```
--action getProjectList --help
```
Use:
- Double dashes (--) for multi-letter parameters, such as --help
- Single dash (-) for short options listed in the help’s Short column, such as -v
Most parameters require a value unless otherwise indicated. Boolean flags, like --verbose, do not take a value.
Parameter names are case-sensitive. For example:
- --userid is invalid
- --action addpage is equivalent to --action addPage
If you specify a parameter using the wrong case, the CLI will return an "unknown parameter" error and display the correct usage (version 9.8+).
Some parameters accept both short and long forms, such as -a and --action. You must use only one form per command.
Parameters with default values will have those values noted in the help output.
Enclose values that contain spaces or special characters in double quotes:
```
--title "this is my title"
```

3. Quoting rules by platform

Quoting behavior varies by terminal environment. Pay close attention to escaping requirements:

Windows and CLI scripts (all platforms):

Escape embedded double quotes by doubling them.

--common "-a addComment --comment ""This is a quoted string"""

Linux and macOS:

Use a backslash (\) to escape embedded double quotes.

--common "-a addComment --comment \"This is a quoted string\""

Alternative quoting:

You can sometimes use single quotes around the entire string and double quotes inside:
```
--common '-a addComment --comment "Quoted string inside single quotes"'
```

4. Handling lists and newlines

Parameters that accept comma-separated lists must wrap values containing commas in single quotes:
```
--custom "'first:a,b,c',second:x"
```
If a quoted value contains a single quote, escape it by doubling the single quote.
Some text fields support \n (with spaces) to insert newlines:
```
--description "Multi-line text:\n # line 1\n # line 2"
```

5. Using the `--special` parameter for special character substitution

Special characters can interfere with CLI parsing, terminal behavior, or parameter formats (for example, lists or key-value pairs). Use the --special parameter to define alternate characters that the CLI will replace after parsing.

Substitution table

Position	Original Character	Use Case	Suggested Alternate
1	`,`	Comma-separated lists
2	`:`	Colon-separated values	`#`
3	`@`	Variable replacement (`@...@`)
4	`'`	Single quotes in value lists
5	`"`	Quoting strings with spaces	`~`
6	`^`	Double quote substitution marker

Leave a position blank if you don’t want to replace that character.
Example:

--special " #  ~"
--common "--findReplace ~find this:thing#replace with~"

This replaces : with # and " with ~ in the parameter values. The CLI performs the substitution only after parsing is complete.

Not all parameters currently support this feature, but coverage continues to expand as new use cases are identified.

6. Scripting tips

When using CLI commands in scripts:

Lines starting with # are treated as comments and are logged.
Lines starting with ## are treated as comments and are not logged (CLI version 12.1+).

7. Character encoding

Ensure all usernames and passwords use the ISO-8859-1 character set. Avoid characters that your OS terminal requires you to escape. Using unsupported or improperly encoded characters can trigger authorization errors such as:

User is not authorized to perform the request.

8. Product compatibility and licensing

The Atlassian CLI requires that the target Atlassian product supports the remote APIs needed for the requested actions. Atlassian provides broad API coverage, but some actions may require product-specific enhancements. You can request or vote for remote API features through Atlassian's public issue tracker.

The Atlassian CLI is licensed software. For licensing details, see the ACLI License.