Configuration

This configuration model applies to Atlassian Confluence Cloud only. acs2md does not support Confluence Server or Confluence Data Center.

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

Priority	Source	Example
1 (lowest)	Built-in defaults
2	Config file	(see below)
3	Environment variables	`ACS2MD_CONFLUENCE_DOMAIN`
4 (highest)	CLI flags	`--log-level debug`

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

macOS

~/Library/Application Support/acs2md/

- - - - config.yaml
      - license.bin

Linux

~/.config/acs2md/ (or $XDG_CONFIG_HOME/acs2md/ if the environment variable is set)

- - - config.yaml
    - license.bin

Windows

%AppData%\acs2md\ (typically C:\Users\<username>\AppData\Roaming\acs2md\)

- - - config.yaml
    - license.bin

Full config file reference


# Confluence connection
confluence:
  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: 10ms # Initial request timeout
    max_timeout: 100ms # 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: "" # Directory to cache downloaded images
  max_size_bytes: 10485760 # Maximum size per image (default 10 MB)

Environment variables

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

Environment variable	Config key	Description
`ACS2MD_CONFLUENCE_DOMAIN`	`confluence.domain`	Confluence instance domain
`ACS2MD_CONFLUENCE_USERNAME`	`confluence.username`	Atlassian account email
`ACS2MD_CONFLUENCE_API_TOKEN`	`confluence.api_token`	Confluence API token
`ACS2MD_HTTP_CLIENT_MAX_RETRIES`	`http.client.max_retries`	Retry count
`ACS2MD_HTTP_CLIENT_BASE_TIMEOUT`	`http.client.base_timeout`	Base request timeout
`ACS2MD_HTTP_CLIENT_MAX_TIMEOUT`	`http.client.max_timeout`	Max request timeout
`ACS2MD_HTTP_CLIENT_PROXY`	`http.client.proxy`	HTTP proxy URL
`ACS2MD_LOG_LEVEL`	`log.level`	Log level
`ACS2MD_LOG_FORMAT`	`log.format`	Log format
`ACS2MD_LOG_FILE`	`log.file`	Log output file
`ACS2MD_DEBUG_ENABLED`	`debug.enabled`	Enable debug mode
`ACS2MD_IMAGE_CACHE_DIR`	`image.cache_dir`	Image cache directory
`ACS2MD_IMAGE_MAX_SIZE_BYTES`	`image.max_size_bytes`	Max image size

Global CLI flags

These flags are available on every command:

Flag	Default	Description
`--config-file`	(see `config where`)	Path to a custom config file
`--log-level`	`info`	Log verbosity: `debug`, `info`, `warn`, `error`
`--log-format`	`text`	Log format: `text` or `json`
`--log-file`	(discard)	Write logs to `stdout`, `stderr`, or a file path
`--debug`	`false`	Shorthand for `--log-level=debug`
`--image-cache-dir`	(none)	Directory for caching downloaded images
`--image-max-size-bytes`	`10485760`	Max size in bytes for cached images

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.

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"

Avoid storing proxy credentials in the config file if it is shared or version-controlled. Use the ACS2MD_HTTP_CLIENT_PROXY environment variable instead.

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