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: Install the released binary

Released builds are currently available for macOS and Linux only. Windows builds are not part of the current released artifacts.

Pick the section that matches the workstation where the tool will run.

Install on macOS

acp2md for macOS is distributed as a universal .pkg installer for Apple Silicon and Intel systems. Released binaries are published on the GitHub Releases page. Use the Climakers store for plan selection, purchase, and license activation, then download the released installer from GitHub.

To download the released installer and checksum:


VERSION=v1.0.0
curl -L -o acp2md.pkg \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-darwin-universal.pkg"
curl -L -o acp2md.pkg.sha256 \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-darwin-universal.sha256"

Verify the checksum before installation:


echo "$(cat acp2md.pkg.sha256)  acp2md.pkg" | shasum -a 256 -c -

Then open acp2md.pkg with a double click in Finder and follow the installer prompts, or install it non-interactively:


sudo installer -pkg acp2md.pkg -target /

Install on Linux

acp2md for Linux is distributed as a zip archive per architecture on the GitHub Releases page. The release also ships a checksum file and an optional Sigstore bundle for customers with supply-chain verification requirements.


VERSION=v1.0.0
ARCH=amd64
curl -L -o acp2md.zip \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-linux-${ARCH}.zip"
curl -L -o acp2md.zip.sha256 \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-linux-${ARCH}.sha256"

To verify the downloaded checksum:


echo "$(cat acp2md.zip.sha256)  acp2md.zip" | sha256sum -c -

If you need provenance verification as well, download the optional Sigstore bundle and verify it with Cosign:


curl -L -o acp2md.sigstore.json \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-linux-${ARCH}.sigstore.json"
unzip -q acp2md.zip
cosign verify-blob \
  --bundle acp2md.sigstore.json \
  --certificate-identity-regexp 'https://github\.com/climakers/ac2md/\.github/workflows/release\.yaml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ./acp2md

Unpack and place the binary on PATH:


unzip -q -o acp2md.zip
chmod +x acp2md
sudo mv acp2md /usr/local/bin/acp2md

Windows .exe binaries are not currently shipped as release artifacts. Windows users can build from source if needed, but released customer artifacts remain macOS and Linux only.

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