Use findReplace and findReplaceRegex to customize content in ACLI

The findReplace and findReplaceRegex parameters give you powerful tools for content automation in Atlassian Command Line Interface (ACLI) actions. These parameters let you define templates that can be reused with specific, dynamic substitutions. The replacements happen at the time the action runs.

You can use these parameters for anything from simple text replacements to complex regular expression (regex) logic. This is especially helpful when working with page templates, scripted actions, or automated workflows.

How `findReplace` and `findReplaceRegex` work

The findReplace and findReplaceRegex parameters let you search for specific text or patterns and replace them with something else. This is string manipulation and doesn't evaluate variables or logic—it's purely find and replace.

You can use these parameters in several ways:

1. Perform a simple replacement

Replace one string with another.

--findReplace XXX:YYY

This finds every instance of XXX and replaces it with YYY. The format uses a colon (:) to separate the original string from the replacement.

2. Use multiple replacements

Provide more than one --findReplace to apply multiple changes in a single command.

--findReplace AAA:BBB --findReplace XXX:YYY

Each replacement executes in the order listed.

3. Use regular expressions

Use findReplaceRegex for pattern-based replacements.

--findReplaceRegex XXX-(\d+):YYY-$1

In this example, the first part is a regular expression that captures a numeric value using (\d+). The replacement string YYY-$1 inserts that captured value using $1. You can use additional groups with $2, $3, and so on.

Tip: Refer to the regular expressions reference for more on capture groups and syntax.

4. Handle strings with spaces

If your replacement text includes spaces, enclose the entire pair in double quotes.

--findReplace "AAA BBB:YYY ZZZ"

As with any CLI parameter that includes spaces, quoting is required.

5. Use special characters and embedded quotes

If your content includes colons, quotes, or other special characters, wrap the values in single quotes to avoid parsing issues.

--findReplace 'AAA:BBB':YYY

For more complex values—especially ones with multiple separators or quotes—this can become hard to read and maintain. In these cases, use the --special parameter to redefine the separator and quoting characters, making your command cleaner and easier to manage. For example, Confluence storage format is a common scenario that benefits from using --special.

Example use cases

You can apply findReplace and findReplaceRegex to many ACLI actions. Below are some common examples:

1. Run a file of parameterized actions

Use findReplace to inject custom values into a file of actions executed with the run action.

--action run --file my-actions.txt --findReplace PROJECTKEY:ABC

2. Copy Confluence pages as templates

Use the Confluence CLI copyPage action to clone a page hierarchy and replace content dynamically.

--action copyPage --space "TEMPLATE" --title "Template Page" \
--newSpace "PROJECT" --newTitle "Project Plan" \
--findReplace "@projectName@:New Project"

3. Modify existing Confluence pages

Update content using modifyPage and findReplace.

--action modifyPage --space "DOC" --title "Release Notes" \
--findReplace "@version@:2.1.0"

This lets you keep your documentation up to date with minimal effort.