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

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

acs2md-<version>-darwin-universal.pkg — macOS installer (Apple Silicon and Intel)
acs2md-<version>-linux-amd64.zip — Linux x86-64
acs2md-<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

acs2md for macOS is a signed, notarized universal .pkg installer for Apple Silicon and Intel systems. Download acs2md-<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 "acs2md-${VERSION}-darwin-universal.sha256"
sudo installer -pkg "acs2md-${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

acs2md 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 "acs2md-${VERSION}-linux-${ARCH}.sha256"
unzip -q -o "acs2md-${VERSION}-linux-${ARCH}.zip"
chmod +x acs2md
sudo mv acs2md /usr/local/bin/acs2md

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