Confluence CLI

CLI tool for interaction with Confluence such as creating and updating pages.

What is this repository for?

This tool is used to script creating or updating Confluence pages, typically in a CICD pipeline, e.g:

• automatically generate documentation in Confluence
• create a blueprint for creating a set of pages
• generate templated content from structure data, such as unit test results

Installation

Requires Node.js 18 or above.

1. Install the tool (with global option):

Yarn:

yarn global add @rushdigital/confluence-cli

NPM:

npm install -g @rushdigital/confluence-cli

Or install from source:

yarn global add https://bitbucket.org/rushdigital/confluence-cli.git

2. Set environment variables

[email protected]
CONFLUENCE_PASSWORD=API-token

See Create an API token article for more details.

Basic Usage

Create page

echo "<h1>Hello World</h1>" \
  | confluence-cli page create https://mydomain.atlassian.net/wiki/spaces/TST/pages/1001/Parent --title "Hello world"

Get page content

confluence-cli page get https://mydomain.atlassian.net/wiki/spaces/TST/pages/1002/Hello+World

Update page

echo "<h1>Hello World</h1><p>updated<p>" \
  | confluence-cli page update https://mydomain.atlassian.net/wiki/spaces/TST/pages/1002/Hello+World --title "Hello world (updated)"

Page ids

Note that you can use page ids instead of page urls as well. If so, you'll seen to pass you domain via --domain parameter or set it via CONFLUENCE_DOMAIN environment variable. E.g:

confluence-cli page get 1002 --domain myaccount
# or
CONFLUENCE_DOMAIN=myaccount confluence-cli page get 1002

Advanced Usage

Simple Templating

You can add content placeholders to pages, and they can be replaced with the tool. Placeholders are in the form ${name}.

You can use them to create pages from a template, replacing values:

echo "<h1>Hello ${NAME}</h1>" | confluence-cli content placeholder NAME --content "World" | confluence-cli page update 1002 --domain myaccount

Updateable placeholder

To keep the placeholder updateable multiple times add --swappable.

E.g. Add ${LAST_UPDATED} to a page and update it with current date/time:

echo "<p>Last updated: ${LAST_UPDATED}</p>" \
  | confluence-cli page update 1002 --domain myaccount

confluence-cli page get 1002 --domain myaccount \
  | confluence-cli content placeholder LAST_UPDATED --content "$(date)" --swappable \
  | confluence-cli page update 1002 --domain myaccount

Advanced Templating

For more advanced scenarios, e.g. rendering a list of items from a JSON or a YAML file, there's Handlebars template support.

E.g. let say you have a data source data.json:

{
  "name": "World",
  "items": ["Item 1", "Item 2"]
}

And you've setup a template test.hbs:

<h1>Hello {{name}}</h1>
<ul>{{#items}}
  <li>{{.}}</li>
{{/items}}</ul>
<p>Generated at {{now}}</p>

Run:

confluence-cli content render --input data.json --template test.hbs

The output will be:

<h1>Hello World</h1>
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>
<p>Generated at 10/17/2022, 11:24:38 PM</p>

Updating Tasks

You can update the tasks (check boxes) on a page. If tasks are added to the page manually they have a sequential integer id, so can usually guess the id from position on the screen. Then use it to update the task state.

confluence-cli page get 12345 | confluence-cli content task 1 --status "complete" | confluence-cli page update 12345

You can also update task text by adding --content "..." parameter

To update multiple tasks in one go use the tasks command variant:

confluence-cli page get 12345 | confluence-cli content tasks tasks.yaml --id "taskId" --template task.hbs | confluence-cli page update 12345

tasks.yaml would be the source data for the task states, e.g:

- taskId: 1
  status: complete
  text: Automaticallly ticked
- taskId: 2
  status: incomplete
  text: Automaticallly unticked
- taskId: 3
  text: Left unchanged

--id "taskId" specifies the property to use for the task id (to match tasks on the page)

task.hbs is a Handlebars template to use to replace task content with, e.g:

<ac:task>
  <ac:task-id>{{id}}</ac:task-id>
  <ac:task-status>{{new.status}}{{^new.status}}{{old.status}}{{/new.outcome}}</ac:task-status>
  <ac:task-body><span class="placeholder-inline-tasks">{{{old.content}}}. {{#new.text}}</span></ac:task-body>
</ac:task>

The context the template will get:

• id - task id
• old - existing task details (as currently on the page):
  • status - complete or incomplete
  • content - Content of the task
• new - item from the datafile

Command Reference

• confluence
  • content
    • placeholder
    • render
    • task
    • tasks
  • page
    • create
    • get
    • update

Security Updates

To fix security updates, in develop branch:

1. Run npm audit to check for vulnerabilities.
2. Run npm run update:dependencies to fix discovered vulnerabilities (if fixes are available) and update other dependencies.
3. Run npm run test to ensure things are working as expected.
4. Run npm audit to check that vulnerabilities have been fixed.
5. Commit changes to the repository, adding details of the vulnerabilities that have been fixed to the commit message (CVE number and vulnerable packages).
6. Run npm run version:next to bump the version number and create a new tag.
7. Push to origin and wait for the the build pipeline to finish successfully.
8. Merge develop to master with Fast-forward strategy.
9. Push to origin and wait for the the build pipeline to publish a new version of the package to npm.

Support

If you find a bug or have a feature request please log it at https://bitbucket.org/rushdigital/confluence-cli/issues

About RUSH

RUSH was founded on a simple principle; the exhilarating feeling of solving a difficult problem, a feeling that is common in the challenging projects RUSH tackles. We’re committed to bringing this enthusiasm to our work as a forward-looking, tech-engaged business with the purpose statement: We design and build technology to better serve humankind.

Our ways of working have been tested in some of the most demanding and impactful projects, resulting in effective and elegant award-winning digital experiences that millions of people benefit from every day.

We strive for continuous improvement to refine our practices and processes - like this tool, created to automate repetitive tasks and make the teams' lives easier. If you'd like to join or learn more about RUSH's team of strategic thinkers, empathetic designers and technical mavericks visit rush.co.nz/careers

License

CC-BY-NC-SA-4.0