Skip to main content

Configuration Precedence

The CLI resolves configuration from command-line options, YAML, environment variables, and defaults. Command-line values take priority over mapping file values.

The important rule is: the leftmost configured value wins. Environment variables are only supported for authentication and API target settings.

General Rule​

For most check, CSV, output, PDF, filter, and folder settings:

  1. Command-line option
  2. YAML mapping file
  3. Built-in default

In short:

CLI flag -> YAML (--map) -> Default

Examples:

  • --col-vat-id overrides columns.vatId.
  • --in-encoding overrides input.encoding.
  • --pdf enables PDF even if defaults.pdf is false.
  • --no-pdf disables PDF even if defaults.pdf is true.
  • --no-sign disables signing even if defaults.sign is true.

Put fixed settings in the YAML mapping file:

  • CSV delimiter and encoding.
  • Column mapping.
  • Output column selection.
  • PDF defaults.
  • Folder mode settings such as pattern, minimum file age, and duplicate mode.

Use command-line flags for one-off changes:

  • --env test
  • --base-url
  • --out
  • --dry-run
  • --force-new
  • -v or --verbose

This keeps automated jobs repeatable while still letting you override behavior for a specific run.

Authentication​

Token resolution:

  1. --token
  2. OPTIMUS_TOKEN
  3. empty value

Real API runs fail when the final token is empty. Dry runs do not require a token.

API Target​

API target resolution:

  1. --base-url
  2. OPTIMUS_BASE_URL
  3. --env
  4. OPTIMUS_ENV
  5. Production URL

--env and OPTIMUS_ENV support:

  • test
  • prod

For API target settings, the effective priority is:

CLI flag -> Environment variable -> Default

YAML does not currently define token, environment, or base URL values.

Check Type​

Check type resolution:

  1. --standard
  2. --qualified
  3. defaults.checkType

The final value must be Standard or Qualified. The CLI accepts lowercase YAML values such as standard and qualified.

Retry Duration​

Retry duration resolution:

  1. --retry-duration
  2. defaults.retryDuration
  3. None

Accepted values are:

  • None
  • OneHour
  • TwoHours
  • FourHours
  • EightHours
  • TwentyFourHours

The CLI also normalizes short forms such as 1h, 2h, 4h, 8h, and 24h.

Output Columns​

Output column resolution:

  1. --out-columns
  2. output.columns
  3. Default output columns

Unknown output columns cause a configuration error unless the column is defined under customColumns.