Skip to main content

Getting Started

This page shows the shortest safe path from an input CSV to a result CSV.

The CLI is designed for systems that can export CSV files but cannot connect directly to an API. After setup, your ERP or job scheduler can export files, the CLI can validate them automatically, and the result CSV can be imported back into your process.

Prerequisites​

You need:

  • The optimus command installed and available in your terminal.
  • An Optimus API token.
  • A CSV file with a VAT ID column.
  • A mapping file that tells the CLI which CSV columns to use.

Verify the CLI is available:

optimus --version

Create A Mapping File​

Create mapping.yml next to your CSV file:

columns:
  vatId: "VatId"
  name: "CompanyName"
  street: "Street"
  zip: "PostalCode"
  city: "City"

customColumns:
  customer_number: "CustomerNumber"

input:
  delimiter: ";"
  encoding: "utf-8"
  hasHeader: true

output:
  delimiter: ";"
  encoding: "utf-8"
  bom: true

defaults:
  checkType: standard
  retryDuration: None

Only columns.vatId is required. If name, street, zip, and city are provided, Optimus verifies each component against the responsible state authorities.

customColumns are copied into the result CSV. They are not sent to the validation API.

Prepare A CSV File​

For the mapping above, the input CSV can look like this:

VatId;CompanyName;Street;PostalCode;City;CustomerNumber
DE284700631;Optimus Software GmbH;Tal 44;80331;München;C-1001
DE000000000;Example GmbH;Main Street 1;10115;Berlin;C-1002

Configure Your Token​

Use an environment variable so the token does not appear in command history:

export OPTIMUS_TOKEN="<token>"

On Windows PowerShell:

$env:OPTIMUS_TOKEN = "<token>"

Run A Dry Run First​

Dry-run mode validates the file and mapping without calling the API:

optimus check customers.csv --map mapping.yml --standard --dry-run

Use this before real validation when you are creating or changing a mapping file. The output shows the first 5 checkable rows that would be sent to the API, which helps confirm that column mappings select the expected CSV values.

Run The Validation​

Run a standard check:

optimus check customers.csv --map mapping.yml --standard

Run a qualified check:

optimus check customers.csv --map mapping.yml --qualified

The check type can also come from defaults.checkType in the mapping file. If neither the command nor the mapping file sets it, the CLI reports a configuration error.

Review The Result​

For customers.csv, the default result path is:

customers_result.csv

The result includes the input VAT ID, validation status, field match statuses, determined values when returned by the API, custom columns from your mapping, and checked_at.

Example result:

row;customer_number;vat_id;vat_id_status;name;name_status;name_determined;street;street_status;street_determined;zip;zip_status;zip_determined;city;city_status;city_determined;checked_at
1;C-1001;DE284700631;Valid;Optimus Software GmbH;Match;;Tal 44;Match;;80331;Match;;München;Match;;2026-05-13T09:15:00Z
2;C-1002;DE000000000;Invalid;Example GmbH;;;Main Street 1;;;10115;;;Berlin;;;2026-05-13T09:15:01Z

The run also writes a support log unless you use --no-log.