Skip to main content

Configuration

Settings resolve in this order, highest priority first:

  1. Command-line option (--env, --base-url, --token, …)
  2. Environment variable
  3. Persisted config file
  4. Default: the test environment
caution

This order also applies to the access token. A token saved with ebsi auth token --save is stored in the config file, so an EBSI_ACCESS_TOKEN variable left in your environment (for example a stale one in a shell profile or CI) silently overrides it, as does --token. If writes fail with an authentication error after you obtained a fresh token, unset EBSI_ACCESS_TOKEN.

Environment variables​

VariableDescription
EBSI_ENVDefault environment
EBSI_API_BASE_URLAPI base URL, including the /v1 prefix
EBSI_CHAIN_IDEVM chain id of a local node (decimal or hex). Ignored by the other environments
EBSI_OUTPUTDefault output format (pretty, json, table)
EBSI_ACCESS_TOKENBearer token for write operations
EBSI_ES256K_PRIVATE_KEYsecp256k1 private key (0x-prefixed hex)
EBSI_ES256_PRIVATE_KEYP-256 private key (hex)
EBSI_SIGN_ALGES256 or ES256K
EBSI_VCDM_VERSION1.1 or 2.0
EBSI_DIDEBSI DID to use as subject or holder
EBSI_ALLOW_UNTRUSTED_NODESet to 1 to only warn about nodes missing from the Trusted Nodes List
EBSI_TNL_URLWhere to download the Trusted Nodes List from (default https://tnl.ebsi.eu)

Write commands also read the contract address of each registry from an environment variable. See ledger write.

Environments​

EnvironmentBase URL
localhttp://localhost:3000/v1
testhttps://api-test.testnode02.ebsi.eu/v1
pilotNo default. https://api-pilot.ebsi.<domain>/v1, set with --base-url
preprodNo default. https://api-preprod.ebsi.<domain>/v1, set with --base-url
prodNo default. https://api.ebsi.<domain>/v1, set with --base-url

pilot, preprod and prod are served by each node operator under their own domain, so the CLI has no default for them. Without a base URL, it asks you to pick one of the trusted nodes. You can also pair --env with --base-url:

ebsi --env preprod --base-url https://api-preprod.ebsi.node1.example.org/v1 did-registry identifiers list

The --env value also determines the EBSI network for which the CLI signs credentials and mints ebsi: URIs.

Persisted config file​

ebsi config set saves settings so you don't have to pass options every time:

# Use the pilot environment by default
ebsi config set env pilot

# Always output JSON
ebsi config set output json

# Persist the secp256k1 key and an optional P-256 key
ebsi config set es256kPrivateKey 0x...
ebsi config set es256PrivateKey 0x...

# Persist which key signs VCs and VPs when both are configured
ebsi config set signAlg ES256

# Read a value (the output includes the config file location)
ebsi config get env

Valid keys: chainId (local environment only), did, env, es256PrivateKey, es256kPrivateKey, output, signAlg, token, vcdmVersion.

caution

es256PrivateKey and es256kPrivateKey are stored in plaintext in the config file. In production, use environment variables or per-command options instead.

Trusted Nodes List​

For pilot, preprod and prod, the CLI only talks to nodes of the signed Trusted Nodes List (TNL). You can browse it in the Trusted Nodes List tool.

  • The list is downloaded and verified (signatures, expiry, rollback) at startup, then cached locally. It is checked again after an hour, and refreshed in the background in interactive mode.
  • If the list can't be refreshed, a cached copy that still verifies is used, with a warning. Otherwise the command fails.
  • A command whose base URL is not a trusted node of --env is refused. With --allow-untrusted-node (or EBSI_ALLOW_UNTRUSTED_NODE=1), you only get a warning.
  • When pilot, preprod or prod has no base URL, the CLI asks you to pick a trusted node and saves your choice in the config file. If that node later leaves the list, you are asked again. Without a terminal, the command fails and prints the trusted nodes.
  • local and test are not covered. The config, wallet and tnl commands never call a node, so they skip the check.