Configuration

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

In practice, this means you can keep stable workstation settings in the config file, inject secrets through environment variables, and override behavior per run with CLI flags.

Config file location

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

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

acp2md 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, acp2md anchors the cache at <output-dir>/.image_cache beside the sync state file, or ./.image_cache when writing to stdout. 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 ACP2MD_ 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 'acp2md config set
                        http.client.base_timeout 500ms' and ...

Then raise them:

acp2md config set http.client.base_timeout 500ms
acp2md 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

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

With authentication:

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

Logging to a file

acp2md page convert by-id 123456 --log-file app.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:

acp2md page convert by-id 123456 --log-file stdout