ACLI Companion for Atlassian

This VS Code extension from Appfire augments the Atlassian Command Line Interface (ACLI), an automation tool for Atlassian products like Jira, Confluence, and Bitbucket.

This extension includes rich support for editing ACLI script files as well as help searching and building ACLI actions, as detailed below.

You can find additional information, tips and support for ACLI in:

• Documentation
• Support
• Community

Prerequisites

To use this extension, you must have already installed ACLI version 10.4 or later.

Once installed, you will need to configure this extension with the location of your ACLI executable file, described in the "Extension Settings" section below.

Features

Major features included with this extension are:

• Quick links to documentation, support, and community sites via the Command Palette
• Support for authoring and maintaining ACLI script files (files ending with .acli), including:
  • Syntax highlighting
  • Action and parameter help on mouse hover
  • Basic error reporting such as unrecognized action and parameter names
  • Run scripts directly in the IDE, capturing output to a new editor with its own syntax highlighting
  • Autocompletion for parameter and action names
• Quick access to the ACLI shell via the Command Palette
• Syntax highlighting for ACLI action output (either when run via the IDE or when viewing log files with the extension .aclilog)
• An explorer tree view for action discovery
• An action favorite tree view for keeping track of your most commonly used actions
• A form-based action builder

Extension Settings

Check out our Walkthrough, which will help you configure and test the extension. From the Command Palette, type walkthrough, choose "Get Started: Open Walkthrough..." and then find and select "Get Started with ACLI."

The extension contributes the following settings:

• acli.installation.scriptPath: specifies the absolute file path on your system to the installed ACLI executable (i.e., the actual acli file that is run). In most situations it is sufficient to provide only the absolute path to the ACLI installation directory but specifying the exact executable file path is the most reliable value to use.

  Platform-specific examples:

  • Windows: C:\Users\MyName\ACLI\acli.bat
  • macOS: /Users/MyName/ACLI/acli
  • Linux: /home/myname/ACLI/acli

You may also need to check whether or not your distribution adds a .sh extension to the executable name (e.g., for Linux).

Commands

Open the Command Palette and type ACLI to find all available ACLI commands.

ACLI: Open Documentation|Support|Community Site

The ACLI: Open * commands open the named site in your external browser. These simple conveniences help you to quickly get the help you need.

ACLI: New Shell

This command opens a new ACLI shell in a new integrated terminal instance. The shell's rich auto-completion capabilities can be used to quickly compose and test ACLI actions against live Atlassian products (and more!). This can be useful when exploring or performing singular actions, or authoring or maintaining new ACLI script files in an editor.

ACLI: Run Script

This command runs the ACLI script in the current editor. The action output appears in a new Output channel (see Panels). The working directory for the script execution is the same directory that contains the script.

ACLI Script File Support

Syntax Highlighting

The extension supports syntax highlighting for ACLI script files (.acli file extension) and ACLI script output logs (.aclilog file extension).

Action and Parameter Mouse Hover Help

In an ACLI script, you can hover the mouse pointer over an action or parameter to display help information.

Diagnostics

The diagnostics consist of a set of errors and warnings that help you to identify problems in your script, and point to unrecognized actions or parameters.

Parameter and Action Autocompletion

While ACLI Companion provides basic auto-completion for parameters and actions, note that the auto-completion available in the ACLI shell is far more powerful. (It is often useful to first construct an action in the shell or Action Builder, then insert the completed action into the script you are developing.)

When editing scripts, we recommend you to use ACLI: New Shell command to access the ACLI shell from VS Code and use its higher-level action explorer/builder capabilities.

Action Tools

Use the Action Tools to explore and interact with the full range of ACLI actions. The ACLI Action Tools are available via the Activity Bar. Select the tab as shown to reveal what's available:

Action Favorites

This is a tree view of actions, marked as your personal favorites. The view is empty to begin with, and it can be manually populated from the Action Explorer or the Action Builder (both described below).

Action Explorer

The Action Explorer provides an interactive tree view of available ACLI Actions. Because ACLI contains hundreds of actions, this view only shows the most popular ones by default. The view controls on this section can be used to toggle between showing all actions or only those marked as popular.

Additional controls are:

• Expanding or collapsing all nodes in the tree

• Open a quick-pick that allows you to search actions by fuzzy matching on their taxonomical names (<client>:<category>:<action>)

  The list of actions in the quick-pick are limited to those displayed in the tree, so to search through all actions, you need to toggle the Explorer to show all actions, otherwise only the popular actions are searched.

  (Since this is a standard VS Code tree view component, you can also filter the tree view itself to narrow the list of visible actions based on your search input.)

Each action leaf of the tree also contains a context menu (right-click) and an edit button. The available actions here include:

• Copy Action Name to Clipboard - copies the current name to your OS clipboard
• Insert Action Name - inserts the action name into the active editor, if there is one
• Toggle Action Favorite - toggles whether or not this action appears in the Action Favorites tree

A major feature of the extension is the the Action Builder view, use the "edit" button on an action name to access this view as described next.

Action Builder

The ACLI Action Builder provides a form-based view. The form-based view displays the parameters that an ACLI action requires to perform the work. As you fill out the form for a given action, the complete ACLI command is rendered underneath for later use.

The built command can be directly run, copied to the OS clipboard, or inserted into the last active editor (if there is one). You may also toggle Action Favorite entries from the builder form view.

Known Issues

This is currently a preview release -- expect quirks and bugs until 1.0.0, but your early feedback is invaluable.