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 bulk export completed” in the right order.

acs2md 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 spaces you intend to export
a valid acs2md license key from store.climakers.com/acs2md, or an offline local license file generated for a restricted environment
network access from the workstation to Confluence Cloud
enough local disk space for the first export
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

acs2md 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 acs2md.pkg \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acs2md-${VERSION}-darwin-universal.pkg"
curl -L -o acs2md.pkg.sha256 \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acs2md-${VERSION}-darwin-universal.sha256"

Verify the checksum before installation:


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

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


sudo installer -pkg acs2md.pkg -target /

Install on Linux

acs2md 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 acs2md.zip \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acs2md-${VERSION}-linux-${ARCH}.zip"
curl -L -o acs2md.zip.sha256 \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acs2md-${VERSION}-linux-${ARCH}.sha256"

To verify the downloaded checksum:


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

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


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

Unpack and place the binary on PATH:


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

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:


acs2md --version
acs2md --version-extended
acs2md config where
acs2md license where

Verified on a live macOS workstation:


$ acs2md --version
v1.0.0

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

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

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

Step 3: Run diagnostics before touching customer content

Run the readiness check before you begin a real space export:


acs2md doctor

This validates the installed license state, configuration, machine identity, and Confluence connectivity in one step.

Step 4: Create the configuration file

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


acs2md config create
acs2md 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


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

Use environment variables

bash / zsh


export ACS2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACS2MD_CONFLUENCE_USERNAME=you@example.com
export ACS2MD_CONFLUENCE_API_TOKEN=YOUR_API_TOKEN

Step 7: Activate the purchased license

Activate acs2md once with the purchased license key:


acs2md 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:


acs2md license activate --license-file ./license.bin

Verify activation:


acs2md 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 bulk export or before handing the workstation to another operator.

Step 8: Re-run diagnostics end to end

After configuration and license activation, re-run:


acs2md doctor

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


🩺 Running diagnostics for acs2md v1.0.0...

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

📊 Result: all 7 checks passed

🎉 acs2md is ready to use!

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

Step 9: Discover the correct target space

Bulk workflows should start with discovery, not with conversion.


# List available spaces
acs2md space list --format json --limit 5
 
# Review the pages in a target space
acs2md space pages by-key TEAMDOCS --format json --limit 10
 
# Review hierarchy before converting
acs2md space pages by-key TEAMDOCS --tree

On v1.0.0, both discovery commands emit structured JSON objects rather than bare arrays. space pages uses --format json; the legacy --json flag is not accepted by the current release.

Step 10: Run the first real bulk export

Find the space key from the Confluence URL. It appears after /wiki/spaces/ and is typically a short uppercase string such as DOCS or MYSPACE.


acs2md space convert by-key TEAMDOCS --output-dir ./docs

If the key is not clear yet, list accessible spaces first:


acs2md space list

If something fails

re-run acs2md doctor first
verify the active config file with acs2md config where
confirm the license state with acs2md license validate
confirm the target space with space list and space pages
use the support command if you need to send a diagnostic bundle to Climakers