Installation and First-Time Setup

This page is the recommended starting point for new customers. It takes a workstation from “nothing installed” to “first successful export completed” in the right order.

acp2md supports Atlassian Confluence Cloud only. It does not support Confluence Server or Confluence Data Center.

Before you begin

Make sure you have:

a Confluence Cloud site such as mycompany.atlassian.net
a Confluence account with read access to the pages you intend to export
a valid acp2md license key from store.climakers.com/acp2md, or an offline local license file generated for a restricted environment
network access from the workstation to Confluence Cloud
administrator rights only for the install step, if your platform requires it

Step 1: Download and install the released package

Released builds are available for macOS and Linux — Linux on both amd64 and arm64. There is no Windows build.

acp2md is delivered through the Climakers store. Purchase a plan or start a free trial at store.climakers.com/acp2md. After checkout, your order page and confirmation email list a download link for every released package and its matching .sha256 checksum file:

acp2md-<version>-darwin-universal.pkg — macOS installer (Apple Silicon and Intel)
acp2md-<version>-linux-amd64.zip — Linux x86-64
acp2md-<version>-linux-arm64.zip — Linux ARM64
a matching .sha256 checksum file for each package

Download the package for your platform together with its .sha256 file into the same folder, then follow the section that matches your workstation.

The download links in your order are tied to your purchase. Keep them private and do not share them outside your organization.

Install on macOS

acp2md for macOS is a signed, notarized universal .pkg installer for Apple Silicon and Intel systems. Download acp2md-<version>-darwin-universal.pkg and its .sha256 from your order, then verify and install (set VERSION to the version shown in your order):


VERSION=v1.0.0   # use the version shown in your Climakers order
shasum -a 256 -c "acp2md-${VERSION}-darwin-universal.sha256"
sudo installer -pkg "acp2md-${VERSION}-darwin-universal.pkg" -target /

You can also open the .pkg with a double click in Finder and follow the installer prompts.

Install on Linux

acp2md for Linux is delivered as a per-architecture .zip archive with a matching .sha256 checksum file. Download the archive for your CPU architecture (amd64 or arm64) and its .sha256 from your order, then verify and place the binary on PATH:


VERSION=v1.0.0   # use the version shown in your Climakers order
ARCH=amd64       # or arm64
sha256sum -c "acp2md-${VERSION}-linux-${ARCH}.sha256"
unzip -q -o "acp2md-${VERSION}-linux-${ARCH}.zip"
chmod +x acp2md
sudo mv acp2md /usr/local/bin/acp2md

Step 2: Confirm the installation

Verify the binary, configuration location, and license location before moving on:


acp2md --version
acp2md --version-extended
acp2md config where
acp2md license where

Verified on a live macOS workstation:


$ acp2md --version
v1.0.0

$ acp2md --version-extended
acp2md v1.0.0 (darwin/arm64, built 2026-03-29T08:23:49Z)

$ acp2md config where
/Users/<user>/Library/Application Support/acp2md/config.yaml

$ acp2md license where
/Users/<user>/Library/Application Support/acp2md/license.bin

Step 3: Run diagnostics before touching customer content

Run the readiness check before you target a real page:


acp2md doctor

This confirms the installed license state, configuration, machine identity, and Confluence connectivity in one step. It is the fastest way to catch setup problems before you start exporting customer content.

Step 4: Create the configuration file

Use the default config file unless you have a specific reason to isolate environments.


acp2md config create
acp2md config where

Open the reported file path in any editor.

Step 5: Generate a Confluence API token

Create a Confluence API token at id.atlassian.com/manage-profile/security/api-tokens.

You need:

your Confluence domain, for example mycompany.atlassian.net
your Atlassian account email
the generated API token

Step 6: Configure Confluence credentials

Use the config file


confluence:
  domain: mycompany.atlassian.net
  username: you@example.com
  api_token: YOUR_API_TOKEN

Use CLI commands


acp2md config set confluence.domain mycompany.atlassian.net
acp2md config set confluence.username you@example.com
acp2md config set confluence.api_token YOUR_API_TOKEN

Use environment variables

bash / zsh


export ACP2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACP2MD_CONFLUENCE_USERNAME=you@example.com
export ACP2MD_CONFLUENCE_API_TOKEN=YOUR_API_TOKEN

Step 7: Activate the purchased license

Activate acp2md once with the purchased license key:


acp2md license activate --license-key YOUR_LICENSE_KEY

If you are working in an air-gapped or restricted environment, activate the local machine-bound license file instead:


acp2md license activate --license-file ./license.bin

Verify activation:


acp2md license validate

The free Trial edition is a 14-day, single-user, single-machine evaluation. After checkout on the Climakers store, activate it with the same license activate --license-key flow used for paid editions.

The license is tied to the current machine, so validate it before the first operational run or before handing the workstation to another operator.

Step 8: Re-run diagnostics end to end

After configuration and license activation, re-run:


acp2md doctor

Sample output from a real workstation session, with tenant and machine details redacted:


🩺 Running diagnostics for acp2md v1.0.0...

  ✅  Configuration file           /Users/<user>/Library/Application Support/acp2md/config.yaml
  ✅  Confluence credentials       <tenant>.atlassian.net (user: <redacted>)
  ✅  Confluence API               connected (212ms)
  ✅  License file                 loaded (<redacted>)
  ✅  License validation           active (<redacted>)
  ✅  Machine ID                   <redacted>
  ✅  Version                      acp2md v1.0.0 (darwin/arm64, built 2026-03-29T08:23:49Z)

📊 Result: all 7 checks passed

🎉 acp2md is ready to use!

If you want the full build metadata outside doctor, use acp2md --version-extended.

Step 9: Discover the correct target before exporting

When teams jump directly into a conversion command, the most common error is targeting the wrong space or wrong page. Use discovery commands first.


# List available spaces
acp2md space list --limit 5
 
# List pages in a known space
acp2md space pages by-key TEAMDOCS --limit 10
 
# Show hierarchy when page location matters
acp2md space pages by-key TEAMDOCS --tree

Step 10: Run the first real page export

Find the page ID from the Confluence URL. It is the number in /pages/123456/.


acp2md page convert by-id 123456 --output my-page.md

You can also convert by title:


acp2md page convert by-title "My Page Title" --output my-page.md

Or work directly from a browser URL:


acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/123456/My+Page" --output my-page.md

If something fails

re-run acp2md doctor first
verify the active config file with acp2md config where
confirm the license state with acp2md license validate
confirm the target page exists by listing it via space pages
use the support command if you need to send a diagnostic bundle to Climakers