Configuration

acs2md applies configuration from four sources, in order of increasing priority:

In practice, this lets teams separate durable workstation defaults from per-run overrides and automation-specific secret handling.

Config file location

The default config file location depends on your operating system. Run:

acs2md config where

Recommended use:

• keep non-secret defaults in the config file
• inject secrets through environment variables when possible
• reserve CLI flags for per-run overrides and debugging

To create a config file with all defaults filled in:

acs2md config create

Full config file reference

# Confluence connection
confluence:
  type: cloud # cloud | server | datacenter — only cloud is supported
  domain: mycompany.atlassian.net # Your Confluence instance domain
  username: you@example.com # Your Atlassian account email
  api_token: YOUR_API_TOKEN # API token from id.atlassian.com
 
# HTTP client behaviour
http:
  client:
    max_retries: 3 # Number of retry attempts on failure
    base_timeout: 500ms # Initial request timeout
    max_timeout: 30s # Maximum request timeout after retries
    proxy: "" # HTTP proxy URL (e.g. http://proxy.corp:8080)
 
# Logging
log:
  level: info # debug | info | warn | error
  format: text # text | json
  file:
    "" # Path to log file; stdout | stderr | /path/to/file.log
    # Each run truncates the file
 
# Debug mode
debug:
  enabled: false # Enables verbose debug output
  dir: debug # Directory for debug artefacts
 
# Image handling
image:
  cache_dir: "" # Set this only when you want a fixed shared cache location
  max_size_bytes: 2097152 # Maximum size per image (default 2 MB)

When image.cache_dir is left unset, generated configs typically omit the key so the per-output default remains the baseline behavior. In that default mode, acs2md anchors the cache at <output-dir>/<space-key>/.image_cache beside the sync state file, or ./.image_cache when writing to stdout. The space key is always appended to --output-dir. Set image.cache_dir explicitly when you need one fixed cache location across exports.

Environment variables

Every config key can be set with an environment variable by prefixing ACS2MD_ and replacing . with _:

Global CLI flags

These flags are available on every command:

Secure configuration practices

• Prefer environment variables for API tokens on shared or managed systems.
• Use config create to establish the expected file shape before editing manually.
• Run doctor after configuration changes so license, credentials, and connectivity are validated together.
• Use a custom --config-file when you need isolated test and production configurations on the same machine.

Retries and rate limiting

Every request goes through one shared HTTP client with a bounded retry budget. Three settings control it:

With the defaults, the three retries wait 500 ms, 1 s and 2 s.

Retry-After is honoured

When Confluence answers a throttled request with 429 or 503 and names a delay, the client waits exactly that long instead of falling back to its own schedule. The server knows how long its window is; the client does not.

A Retry-After longer than 60 seconds is not honoured — the response is surfaced so you can decide, rather than the command appearing to hang. Waiting is interruptible, so Ctrl+C during a rate-limit pause takes effect immediately.

Check with doctor, which reports the total backoff your configuration actually produces and flags one too short to survive a rate limit:

❌  HTTP retry budget   only 70ms total across 3 retries — too short to wait out
                        a rate limit; raise it with 'acs2md config set
                        http.client.base_timeout 500ms' and ...

Then raise them:

acs2md config set http.client.base_timeout 500ms
acs2md config set http.client.max_timeout 30s

An invalid proxy is an error

An unparseable http.client.proxy stops the command instead of logging a warning and continuing without a proxy. Silently sending traffic direct when it was explicitly asked to route it is, on a corporate network, a failure worth stopping for.

Behind a corporate proxy

acs2md config set http.client.proxy "http://proxy.corp.example.com:8080"

With authentication:

acs2md config set http.client.proxy "http://user:password@proxy.corp.example.com:8080"

Logging to a file

acs2md space convert by-key MYSPACE --log-file acs2md.log

Each run truncates the log file, so it always contains only the output of the most recent run. Use stdout or stderr to stream logs to your terminal:

acs2md space convert by-key MYSPACE --log-file stdout