Use output formats and columns to control list output

ACLI provides many list actions that retrieve structured data from applications. These include actions like getIssueList, getProjectList, and getSpaceList. The data returned by these actions often depends on the value of the --outputFormat parameter.

This guide explains how to use output formats effectively and how to stabilize your automation against future changes in app data.

Why use output formats?

Output formats help in two main areas:

1. Maintain upward compatibility

Automation scripts can break when software upgrades introduce changes. The CLI helps protect your automation by using output formats to control which fields appear in the output. This allows us to add support for new fields without changing the output of existing formats.

When we need to expose new fields, we introduce a new output format. You can then opt into the new format only if your use case requires it.

2. Improve performance

List actions can return large amounts of data, but collecting detailed information often requires extra server requests. This can slow down execution and increase server load.

For example, retrieving summary data for a set of items might require only one request. But getting detailed data might require a separate request per item. If you only need the summary, using a basic output format prevents unnecessary overhead.

By choosing the right output format, you can optimize your script for either speed or detail.

Available output formats

Each list action supports one or more output formats. These are listed in the Action Reference under the Output formats column.

• If an action supports multiple formats, you can select one using the --outputFormat parameter.

• The default format (usually 1) is used when no format is specified.

• For maximum detail, you can use:

  --outputFormat 999

  This format includes all available fields but can change between CLI versions. If your scripts are sensitive to changes in the output structure, avoid using outputFormat 999 in automation.

Use the --columns parameter to control output data

In addition to choosing an output format, you can use the --columns parameter to:

• Limit the output to specific fields

• Reorder columns to simplify downstream processing

This technique can make your scripts more robust and easier to maintain.

How to use --columns

Use a comma-separated list of column names (case-insensitive) or column numbers (1-based). For example:

Or, using column positions:

The order in your list determines the column order in the output.