Configuration
Settings resolve in this order, highest priority first:
- Command-line option (
--env,--base-url,--token, …) - Environment variable
- Persisted config file
- Default: the
testenvironment
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
| Variable | Description |
|---|---|
EBSI_ENV | Default environment |
EBSI_API_BASE_URL | API base URL, including the /v1 prefix |
EBSI_CHAIN_ID | EVM chain id of a local node (decimal or hex). Ignored by the other environments |
EBSI_OUTPUT | Default output format (pretty, json, table) |
EBSI_ACCESS_TOKEN | Bearer token for write operations |
EBSI_ES256K_PRIVATE_KEY | secp256k1 private key (0x-prefixed hex) |
EBSI_ES256_PRIVATE_KEY | P-256 private key (hex) |
EBSI_SIGN_ALG | ES256 or ES256K |
EBSI_VCDM_VERSION | 1.1 or 2.0 |
EBSI_DID | EBSI DID to use as subject or holder |
EBSI_ALLOW_UNTRUSTED_NODE | Set to 1 to only warn about nodes missing from the Trusted Nodes List |
EBSI_TNL_URL | Where 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
| Environment | Base URL |
|---|---|
local | http://localhost:3000/v1 |
test | https://api-test.testnode02.ebsi.eu/v1 |
pilot | No default. https://api-pilot.ebsi.<domain>/v1, set with --base-url |
preprod | No default. https://api-preprod.ebsi.<domain>/v1, set with --base-url |
prod | No 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.
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
--envis refused. With--allow-untrusted-node(orEBSI_ALLOW_UNTRUSTED_NODE=1), you only get a warning. - When
pilot,preprodorprodhas 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. localandtestare not covered. Theconfig,walletandtnlcommands never call a node, so they skip the check.