@europeum-ebsi/cli 0.0.0 → 1.0.0-rc.0

package/README.md

@@ -1,98 +1,1140 @@
-![EBSI Logo](https://ec.europa.eu/cefdigital/wiki/images/logo/default-space-logo.svg)
-
-# EBSI Command Line Interface
-
-The EBSI CLI is a Command Line Interface to connect and test some of the EBSI Core Services provided on the European Blockchain Service Infrastructure (EBSI).
-
-**IMPORTANT REMARKS:**
-
-- EBSI CLI is a sample code to help Early Adopters (EA), this is not perfect code (nor audited code) but we share it in beta version to help EA better understanding through real User Code, how to consume EBSI Core Services.
-
-- For optimal stability, we highly recommend to use the [**Node.js version 24.14.1**](https://nodejs.org/en/download).
-
-## Start the tool
-
-You can start the tool by running:
-
-```sh
-npx @europeum-ebsi/cli
-```
-
-When the CLI prompts `==>` it will be ready to receive commands. There is no need to install the package. It needs Node.js v24 or superior version as a prerequisite.
-
-## Documentation
-
-For more details about the use of this tool see the full documentation in https://hub.ebsi.eu/tools/cli
-
-For instructions on bootstrapping a new EBSI network, see [Bootstrap Guide](src/scripts/bootstrap/README.md).
-
-## Publishing
-
-### From main branch
-
-Create `chore/release` branch off `main` and run the following command to bump version and update change log:
-
-```
-pnpm run prepare:release
-```
-
-In the case of a major release run:
-
-```
-pnpm run prepare:release major
-```
-
-Push the changes including the tag:
-
-```
-git push
-git push --tags
-```
-
-Create a PR on Bitbucket and merge it **without squashing it!**
-
-Then, from the updated `main` run:
-
-```
-npm publish
-```
-
-### From upcoming branch
-
-Create `chore/release` branch off `upcoming` and run the following command to bump version and update change log:
-
-```
-pnpm run prepare:release --preRelease=alpha
-```
-
-In the case of a major release run:
-
-```
-pnpm run prepare:release major --preRelease=alpha
-```
-
-Push the changes including the tag:
-
-```
-git push
-git push --tags
-```
-
-Create a PR on Bitbucket and merge it **without squashing it!**
-
-Then, from the updated `upcoming` run:
-
-```
-npm publish --tag upcoming
-```
-
-## License
-
-Copyright (C) 2026 European Union
-
-This program is free software: you can redistribute it and/or modify it under the terms of the EUROPEAN UNION PUBLIC LICENCE v. 1.2 as published by the European Union.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the EUROPEAN UNION PUBLIC LICENCE v. 1.2 for further details.
-
-You should have received a copy of the EUROPEAN UNION PUBLIC LICENCE v. 1.2. along with this program. If not, see <https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12>.
+# EBSI CLI
+
+A command-line interface for interacting with the [EBSI Core API](https://api-pilot.ebsi.eu/docs).
+
+Supports two modes:
+
+- **Interactive TUI** — launch without arguments for a fuzzy-search command palette with inline tips
+- **Non-interactive** — `ebsi <group> <command> [args] [flags]` for scripting and piping
+
+## Installation
+
+The CLI is part of the `core` monorepo. Build and link it locally:
+
+```sh
+pnpm --filter @europeum-ebsi/cli build
+node cli/dist/index.js --help
+```
+
+Or, if the package is linked globally via `npm link` / `pnpm link`:
+
+```sh
+ebsi --help
+```
+
+## Quick start
+
+```sh
+# Check API health (defaults to the test environment)
+ebsi health
+
+# List DIDs
+ebsi did-registry identifiers list
+
+# Get a specific DID document
+ebsi did-registry identifiers get did:ebsi:ziDnioxYYLW1a3FDD
+
+# Run against the pilot environment
+ebsi --env pilot did-registry identifiers list
+
+# Output as compact JSON (useful for piping to jq)
+ebsi --output json did-registry identifiers list | jq '.items[].did'
+```
+
+### Local dev onboarding quickstart
+
+Against a local stack
+
+```
+ rm -rf deployments/31337 && make deploy-all NETWORK=localhost && make finish-setup NETWORK=localhost && make bootstrap NETWORK=localhost && make create-deployer-did NETWORK=localhost && make grant-factory-deploy-policy NETWORK=localhost && make create-root-tao NETWORK=localhost
+```
+
+(see`contracts/deploy-toolkit`'s README), go from nothing to a usable
+`did-registry:write` token in four commands:
+
+to get the attributes of the RTAO did
+
+```sh
+export EBSI_RTAO_DID=$(node -p 'require("./contracts/deploy-toolkit/deployments/31337/deployment.json").soDid')
+export EBSI_RTAO_ATTRIBUTE_ID=0x$(curl -s "http://localhost:3000/v1/issuers-registry/issuers/$EBSI_RTAO_DID/attributes" | jq -r '.items[].id')
+
+```
+
+then you can export the env as follow
+
+```sh
+export EBSI_RTAO_ES256K_PRIVATE_KEY=$(grep '^SUPPORT_OFFICE_ES256K_PRIVATE_KEY=' .env | cut -d= -f2-)
+export EBSI_RTAO_ES256_PRIVATE_KEY=$(grep '^SUPPORT_OFFICE_ES256_PRIVATE_KEY=' .env | cut -d= -f2-)
+export DID_REGISTRY_ADDRESS=0x23dB4a08f2272df049a4932a4Cc3A6Dc1002B33E
+```
+
+```sh
+ebsi wallet create --save
+ebis wallet info # will display you adress and did
+ebsi faucet 0xMYWALLET
+ebsi onboarding onboard --env local --to $DID_REGISTRY_ADDRESS
+ebsi --env local did-registry identifiers get did:ebsi:z... # confirm it resolves
+
+```
+
+`--rtao-es256-key` signs the credential ES256; swap it for `--rtao-es256k-key` to sign
+ES256K where the deployment accepts that. See [`onboarding`](#onboarding) below
+for what each flag does, and
+[the end-to-end walkthrough](#end-to-end-es256-signed-onboarding-against-a-local-stack)
+for the whole sequence including the chain and API.
+
+## Interactive TUI
+
+Run `ebsi` with no arguments (or with `--interactive`) to open the command palette:
+
+```
+ebsi
+```
+
+- **Type** to fuzzy-filter commands by name or description tip
+- **↑ / ↓** (or `j` / `k`) to navigate the list
+- **Enter** to run the selected command
+- **Esc** to clear the search filter
+- **Ctrl-C** to quit
+
+The palette shows command summaries alongside each result so you can discover what each command does without leaving the terminal.
+
+## Global options
+
+These options are available on every command:
+
+| Flag                 | Description                                                                                                                                                                        | Default  |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `--env <env>`        | Target environment: `local`, `test`, `pilot`, `preprod`, `prod`                                                                                                                    | `test`   |
+| `--base-url <url>`   | Override the API base URL (must include the `/v1` prefix). Required for `preprod` and `prod`, whose API host is node-specific (`api-preprod.ebsi.<domain>` / `api.ebsi.<domain>`). | —        |
+| `--token <jwt>`      | Bearer token for write operations. Overrides config/env.                                                                                                                           | —        |
+| `--es256k-key <hex>` | secp256k1 private key (0x-prefixed), mandatory for signing. Overrides config/env.                                                                                                  | —        |
+| `--es256-key <hex>`  | P-256 private key (hex), optional — for signing VCs/VPs only. Overrides config/env.                                                                                                | —        |
+| `--sign-alg <alg>`   | Which key signs VCs/VPs when both are configured: `ES256` or `ES256K`. Overrides config/env.                                                                                       | —        |
+| `--did <did>`        | EBSI DID to use as the subject/holder. Overrides config/env.                                                                                                                       | —        |
+| `--output <format>`  | Output format: `pretty`, `json`, `table`                                                                                                                                           | `pretty` |
+| `--version`          | Print the CLI version                                                                                                                                                              | —        |
+| `--help`             | Print help for any command                                                                                                                                                         | —        |
+
+## Which key signs what
+
+The CLI can hold two keys:
+
+- A **secp256k1** key (`--es256k-key` / `EBSI_ES256K_PRIVATE_KEY`) — **mandatory** for any command that signs anything. It always signs Ethereum transactions (a P-256 key cannot), and it signs VCs/VPs (e.g. the VP in `auth token`) whenever no P-256 key is configured.
+- An optional **P-256** key (`--es256-key` / `EBSI_ES256_PRIVATE_KEY`) — used only for signing VCs/VPs, never Ethereum transactions. Useful against deployments whose Authorisation service restricts a scope's accepted credential format to ES256.
+
+When **both** keys are configured, you must say which one signs VCs/VPs with `--sign-alg <ES256|ES256K>` (or `EBSI_SIGN_ALG` / `ebsi config set signAlg <alg>`) — the CLI refuses to guess. Commands that don't sign anything (`wallet info`, a plain read, …) work fine with both keys configured and no `--sign-alg`.
+
+`onboarding onboard` always signs with the secp256k1 key regardless of `--sign-alg`, since it's the key `insertDidDocument` registers in the DID document; pass `--register-es256-key` to additionally register a configured P-256 key right after, so it can be used to sign afterwards.
+
+> **Migrating from `EBSI_PRIVATE_KEY`:** that variable (and the old `--key` flag) has been replaced. Run `ebsi config set es256kPrivateKey <hex>` (or export `EBSI_ES256K_PRIVATE_KEY`) instead — the CLI errors out with this instruction if it still finds `EBSI_PRIVATE_KEY` set or a persisted `privateKey` entry. `ebsi config get`/`ebsi config set` stay reachable even while that error would otherwise fire on every other command, and running `config set` once clears a stale persisted `privateKey` entry for good — unsetting the environment variable, if that's the source, is on you.
+
+## Configuration
+
+Settings resolve in this priority order (highest wins):
+
+1. Command-line flag (`--base-url`, `--env`, `--token`, `--es256k-key`, `--es256-key`, `--sign-alg`, `--did`, …)
+2. Environment variable (see table below)
+3. Persisted config file (`config.json`, see below)
+4. Default: `test` environment
+
+### Environment variables
+
+| Variable                  | Description                                                         |
+| ------------------------- | ------------------------------------------------------------------- |
+| `EBSI_API_BASE_URL`       | Override the API base URL (must include `/v1` prefix)               |
+| `EBSI_ENV`                | Default environment (`local`, `test`, `pilot`, …)                   |
+| `EBSI_OUTPUT`             | Default output format (`pretty`, `json`, `table`)                   |
+| `EBSI_ACCESS_TOKEN`       | Bearer token for authenticated write operations                     |
+| `EBSI_ES256K_PRIVATE_KEY` | secp256k1 private key, mandatory for signing (0x-prefixed hex)      |
+| `EBSI_ES256_PRIVATE_KEY`  | P-256 private key, optional — for signing VCs/VPs only (hex)        |
+| `EBSI_SIGN_ALG`           | Which key signs VCs/VPs when both are configured (`ES256`/`ES256K`) |
+| `EBSI_DID`                | EBSI DID to use as the subject/holder                               |
+
+### Environment URLs
+
+| Environment | Base URL                                                                  |
+| ----------- | ------------------------------------------------------------------------- |
+| `local`     | `http://localhost:3000/v1`                                                |
+| `test`      | `https://api-test.testnode02.ebsi.eu/v1`                                  |
+| `pilot`     | `https://api-pilot.ebsi.eu/v1`                                            |
+| `preprod`   | No default — `https://api-preprod.ebsi.<domain>/v1`, set via `--base-url` |
+| `prod`      | No default — `https://api.ebsi.<domain>/v1`, set via `--base-url`         |
+
+`preprod` and `prod` are served by each node operator under their own domain
+(e.g. `https://api-preprod.ebsi.node1.example.org/v1`), so the CLI cannot pick
+one for you. Pair `--env` with `--base-url` (or `EBSI_ENV` with
+`EBSI_API_BASE_URL`); the `--env` value still determines the EBSI network the
+CLI signs credentials and mints `ebsi:` URIs for.
+
+```sh
+ebsi --env preprod --base-url https://api-preprod.ebsi.node1.example.org/v1 did-registry identifiers list
+```
+
+### Persisted config file
+
+Use `ebsi config set` to persist settings across sessions so you don't have to pass flags every time:
+
+```sh
+# Always use the pilot environment by default
+ebsi config set env pilot
+
+# Always output JSON
+ebsi config set output json
+
+# Persist the mandatory secp256k1 key (stored in plaintext — use with caution)
+ebsi config set es256kPrivateKey 0xdeadbeef...
+
+# Persist an optional P-256 key, for signing VCs/VPs
+ebsi config set es256PrivateKey 0xdeadbeef...
+
+# Persist which key signs VCs/VPs when both are configured
+ebsi config set signAlg ES256
+
+# Persist an access token
+ebsi config set token eyJ...
+
+# Check the current persisted value
+ebsi config get env
+
+# See where the config file lives
+ebsi config path
+```
+
+Valid keys: `did`, `env`, `es256PrivateKey`, `es256kPrivateKey`, `output`, `signAlg`, `token`.
+
+> **Security note:** `es256PrivateKey`/`es256kPrivateKey` are stored in plaintext in the config file. Use environment variables or pass `--es256-key`/`--es256k-key` per-command in production environments.
+
+## Output formats
+
+| Format   | Description                                                                  |
+| -------- | ---------------------------------------------------------------------------- |
+| `pretty` | Indented, colourised JSON (default on a TTY; plain indented JSON when piped) |
+| `json`   | Compact single-line JSON — ideal for piping to `jq`                          |
+| `table`  | Key/value table for objects; column table for arrays                         |
+
+```sh
+ebsi --output table did-registry identifiers list
+ebsi --output json  timestamp timestamps list | jq '.items | length'
+```
+
+## Command reference
+
+### `health`
+
+```
+ebsi health
+```
+
+Check the health of the EBSI API and its blockchain node.
+
+---
+
+### `openapi`
+
+```
+ebsi openapi json
+ebsi openapi yaml
+```
+
+Fetch the OpenAPI 3.1 specification in JSON or YAML format.
+
+---
+
+### `config`
+
+```
+ebsi config get <key>
+ebsi config set <key> <value>
+```
+
+Read or write a persisted config value.
+
+Valid keys: `did`, `env`, `es256PrivateKey`, `es256kPrivateKey`, `output`, `signAlg`, `token`.
+
+---
+
+### `wallet`
+
+```
+ebsi wallet create [--es256k-key <hex>] [--es256-key <hex>] [--sign-alg <alg>] [--did <did>] [--save]
+ebsi wallet info   [--es256k-key <hex>] [--es256-key <hex>] [--sign-alg <alg>] [--did <did>]
+```
+
+Manage your EBSI signing key(s) and identity.
+
+| Command         | Description                                                                                                                                  |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wallet create` | Generate (or derive from `--es256k-key`) a secp256k1 key pair, optionally alongside a P-256 key, with its DID, JWK(s), and Ethereum address. |
+| `wallet info`   | Show the DID, address, and per-curve kid/thumbprint for the currently configured key(s).                                                     |
+
+**Key and DID generation semantics:**
+
+- The **secp256k1 key** is randomly generated only when none is already configured. Resolution order: `--es256k-key` flag → `EBSI_ES256K_PRIVATE_KEY`/persisted `es256kPrivateKey` → randomly generated. If a key is already configured (e.g. from a prior `--save`, or `EBSI_ES256K_PRIVATE_KEY` in the environment), `wallet create` reuses it rather than generating a new one.
+- The **P-256 key** (`--es256-key`) is entirely optional and never auto-generated — pass it explicitly (or set `EBSI_ES256_PRIVATE_KEY`) to have it derived and, with `--save`, persisted alongside the secp256k1 key.
+- The **DID** is randomly generated on every `wallet create` invocation, independent of whether the key is new or reused, unless `--did` (or `EBSI_DID`/a persisted `did`) is provided. Invoking `wallet create` with an already-configured key therefore still produces a new DID each time, paired with the same key.
+
+To obtain a deterministic, repeatable identity across invocations, specify both `--es256k-key` and `--did` explicitly.
+
+**Options:**
+
+| Flag                 | Description                                                                                        |
+| -------------------- | -------------------------------------------------------------------------------------------------- |
+| `--es256k-key <hex>` | Use this secp256k1 private key instead of generating a random one (0x-prefixed hex).               |
+| `--es256-key <hex>`  | Also derive a P-256 key from this private key (hex), for signing VCs/VPs.                          |
+| `--sign-alg <alg>`   | Which key signs VCs/VPs when both are configured: `ES256` or `ES256K`.                             |
+| `--did <did>`        | Pin a specific EBSI DID (overrides the randomly generated one).                                    |
+| `--save`             | Persist the private key(s) and DID to the config file (stored in plaintext; a warning is printed). |
+
+**Examples:**
+
+```sh
+# Generate a fresh secp256k1 key pair
+ebsi wallet create
+
+# Derive from an existing key without saving
+ebsi wallet create --es256k-key 0xdeadbeef...
+
+# Derive and persist to config
+ebsi wallet create --es256k-key 0xdeadbeef... --save
+
+# Also derive and persist a P-256 key for signing VCs/VPs
+ebsi wallet create --es256k-key 0xdeadbeef... --es256-key 0xc0ffee... --save
+
+# Show the identity tied to the currently configured key(s)
+ebsi wallet info
+```
+
+---
+
+### `faucet`
+
+```
+ebsi faucet <to> [--private-key <hex>] [--amount-in-eth <eth>] [--rpc-url <url>]
+```
+
+Funds an address with ETH on a local development chain.
+
+Unlike every other command, the faucet talks to the JSON-RPC node **directly**
+rather than through the API's `/ledger` proxy — that proxy needs a Bearer token,
+and funding an account is usually the step that comes before it can get one.
+So `--rpc-url` is a node URL, not an API base URL, and `--env` / `--base-url`
+have no effect here.
+
+| Option                  | Default                            | Description                                 |
+| ----------------------- | ---------------------------------- | ------------------------------------------- |
+| `--private-key <hex>`   | Hardhat account #0 (`0xac0974be…`) | Key funding the transfer (0x-prefixed hex). |
+| `--amount-in-eth <eth>` | `1`                                | Amount of ETH to send, e.g. `0.5`.          |
+| `--rpc-url <url>`       | `http://127.0.0.1:8545`            | JSON-RPC endpoint to send the transfer to.  |
+
+**Examples:**
+
+```sh
+# Send 1 ETH from Hardhat account #0 to an address
+ebsi faucet 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC
+
+# Send a smaller amount
+ebsi faucet 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC --amount-in-eth 0.25
+
+# Fund from a different account, against a non-default node
+ebsi faucet 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC \
+  --private-key 0x… --rpc-url http://127.0.0.1:9545
+```
+
+---
+
+### `onboarding`
+
+```
+ebsi onboarding issue-vc [--holder-did <did>] [--holder-thumbprint <thumbprint>]
+                          --rtao-did <did> --rtao-attribute-id <hex>
+                          (--rtao-es256-key <hex> | --rtao-es256k-key <hex>)
+                          [--es256k-key <hex>] [--es256-key <hex>] [--sign-alg <alg>] [--out <file>]
+ebsi onboarding onboard  [--vc <file>] [--rtao-did <did> --rtao-attribute-id <hex>
+                          (--rtao-es256-key <hex> | --rtao-es256k-key <hex>)]
+                          [--es256k-key <hex>] [--es256-key <hex>] [--register-es256-key]
+                          [--to <address>] [--spec <draft14|1.0>] [--not-before <epoch>] [--not-after <epoch>]
+```
+
+Mints and consumes the `VerifiableAuthorisationToOnboard` VC needed to
+onboard a _new_ DID via the `did-registry:invite` scope. There is no HTTP endpoint
+for minting this VC — it's a local signing operation performed by an RTAO
+already registered as `RootTAO` on chain (run
+`pnpm exec hardhat bootstrap --network <network>` in
+`contracts/deploy-toolkit`, or `scripts/tests/setup-rtao.ts` for your own
+DID/keys, to get one).
+
+#### Which key signs the VC
+
+The credential is signed with **ES256** when `--rtao-es256-key` is given, and
+with **ES256K** otherwise. Which one you need depends on the deployment:
+
+- The Authorisation service constrains the `did-registry:invite` **credential** format
+  per scope. Where that constraint is `["ES256"]`, an ES256K-signed VC is
+  rejected outright and you must pass `--rtao-es256-key`.
+- Deployments whose scopes share `SUPPORTED_ALGS` (`["ES256", "ES256K"]`)
+  accept either.
+
+ES256 is therefore the safer choice: every deployment that accepts ES256K for
+this credential also accepts ES256, but not the reverse. It stays opt-in only
+so existing ES256K setups keep working unchanged.
+
+The RTAO's DID Document must carry the matching verification method with an
+`assertionMethod` relationship. Both `hardhat bootstrap` and
+`scripts/tests/setup-rtao.ts` register the ES256K **and** ES256 methods, so an
+RTAO created by either is ready for both.
+
+`--rtao-es256k-key` is optional once `--rtao-es256-key` is set — the secp256k1 key
+signs nothing in that case. At least one of the two is required.
+
+| Command               | Description                                                                                                  |
+| --------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `onboarding issue-vc` | Sign a `VerifiableAuthorisationToOnboard` VC for a holder DID/key.                                           |
+| `onboarding onboard`  | One-shot: mint (or load) the VC, exchange it for a `did-registry:invite` token, and insert the DID document. |
+
+**Options:**
+
+| Flag                           | Description                                                                                                                                                                                                                                                                                           |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--rtao-did <did>`             | The RTAO's DID. Also read from `EBSI_RTAO_DID`.                                                                                                                                                                                                                                                       |
+| `--rtao-es256k-key <hex>`      | The RTAO's secp256k1 private key, signing the VC ES256K. Optional when `--rtao-es256-key` is given. Also read from `EBSI_RTAO_ES256K_PRIVATE_KEY`.                                                                                                                                                    |
+| `--rtao-es256-key <hex>`       | The RTAO's P-256 private key, signing the VC ES256 instead of ES256K. Also read from `EBSI_RTAO_ES256_PRIVATE_KEY`.                                                                                                                                                                                   |
+| `--rtao-attribute-id <hex>`    | The RTAO's Issuers Registry attribute id (from `ebsi issuers-registry issuers attributes list <rtaoDid>`). Also read from `EBSI_RTAO_ATTRIBUTE_ID`.                                                                                                                                                   |
+| `--holder-did <did>`           | (`issue-vc` only) DID to embed as `credentialSubject.id`. Defaults to the configured wallet's DID.                                                                                                                                                                                                    |
+| `--holder-thumbprint <tp>`     | (`issue-vc` only) JWK thumbprint to embed. Defaults to the configured wallet's signing key thumbprint (see `--sign-alg`).                                                                                                                                                                             |
+| `--es256k-key <hex>`           | The **holder's** secp256k1 key — overrides config/env. Not the RTAO's key (see `--rtao-*` above).                                                                                                                                                                                                     |
+| `--es256-key <hex>`            | The **holder's** optional P-256 key — overrides config/env. `onboard` always signs with the secp256k1 key regardless of `--sign-alg` (see below).                                                                                                                                                     |
+| `--sign-alg <alg>`             | (`issue-vc` only) Which of the holder's keys the default `--holder-thumbprint` binds to, when both are configured.                                                                                                                                                                                    |
+| `--out <file>`                 | (`issue-vc` only) Also write the signed VC JWT to this file.                                                                                                                                                                                                                                          |
+| `--vc <file>`                  | (`onboard` only) Use a pre-obtained VC instead of minting one inline.                                                                                                                                                                                                                                 |
+| `--to <address>`               | (`onboard` only) DID Registry contract address. Defaults to `DID_REGISTRY_CONTRACT_ADDRESS`.                                                                                                                                                                                                          |
+| `--spec <draft14\|1.0>`        | (`onboard` only) Which OpenID4VP grant to speak for the `did-registry:invite` token. Default `draft14`.                                                                                                                                                                                               |
+| `--not-before` / `--not-after` | (`onboard` only) Validity window for the inserted DID document. Default `0` / `9999999999`.                                                                                                                                                                                                           |
+| `--register-es256-key`         | (`onboard` only) After registering the DID document, also register the configured `--es256-key` as an additional verification method (`authentication` + `assertionMethod`), so it can sign VCs/VPs afterwards. Requires a P-256 key; mints its own `did-registry:write` token, always ES256K-signed. |
+
+**Examples:**
+
+```sh
+# Mint an ES256-signed onboarding VC for the currently configured wallet
+ebsi onboarding issue-vc \
+  --rtao-did did:ebsi:zRtao... --rtao-es256-key <p256-hex> --rtao-attribute-id 0x... \
+  --out ./onboarding-vc.jwt
+
+# The same VC, signed ES256K instead (only where the deployment accepts it)
+ebsi onboarding issue-vc \
+  --rtao-did did:ebsi:zRtao... --rtao-es256k-key 0x... --rtao-attribute-id 0x... \
+  --out ./onboarding-vc.jwt
+
+# One-shot: mint the VC inline, get a did-registry:invite token, and write the DID document
+ebsi wallet create --save
+ebsi onboarding onboard \
+  --rtao-did did:ebsi:zRtao... --rtao-es256-key <p256-hex> --rtao-attribute-id 0x...
+
+# Same, but with a pre-obtained VC
+ebsi onboarding onboard --vc ./onboarding-vc.jwt
+
+# Now get a plain write token for further did-registry/issuers-registry/... writes
+ebsi auth token --scope did-registry:write --save
+```
+
+#### End-to-end: ES256-signed onboarding against a local stack
+
+The full sequence, from an empty chain to a resolvable DID registered through
+an ES256-signed credential. Four shells; every value the later steps need is
+printed by step 3.
+
+**Shell 1 — chain**
+
+```sh
+cd contracts/deploy-toolkit
+pnpm exec hardhat node --network default
+```
+
+**Shell 2 — contracts and RTAO**
+
+```sh
+cd contracts/deploy-toolkit
+make deploy-all NETWORK=localhost
+
+# Creates the Support Office DID, registers its ES256K *and* ES256
+# verification methods, and self-attests it as RootTAO.
+EBSI_DOMAIN=http://localhost:3000 pnpm exec hardhat bootstrap --network localhost
+```
+
+`bootstrap` prints the three values the CLI needs — keep them:
+
+```
+Support Office ES256 Private Key: <p256-hex>      ->  --rtao-es256-key
+SO DID: did:ebsi:z...                             ->  --rtao-did
+SO Root TAO attribute id: 0x...                   ->  --rtao-attribute-id
+```
+
+(To use your own RTAO keys instead, run `scripts/tests/setup-rtao.ts` with
+`RTAO_DID` / `RTAO_ES256_PRIVATE_KEY` / `RTAO_ES256K_PRIVATE_KEY` set; it
+prints the same DID and attribute id and registers both methods too.)
+
+**Shell 3 — API**
+
+```sh
+pnpm --filter @europeum-ebsi/api start        # serves http://localhost:3000/v1
+```
+
+**Shell 4 — the flow**
+
+```sh
+pnpm --filter @europeum-ebsi/cli build
+alias ebsi="node cli/dist/index.js"
+
+export EBSI_ENV=local
+export EBSI_OUTPUT=json
+export DID_REGISTRY_CONTRACT_ADDRESS=$(
+  jq -r '.system.DidRegistry' contracts/deploy-toolkit/deployments/31337/deployment.json
+)
+
+# From step 3's output:
+export EBSI_RTAO_DID=did:ebsi:z...
+export EBSI_RTAO_ES256_PRIVATE_KEY=<p256-hex>
+export EBSI_RTAO_ATTRIBUTE_ID=0x...
+
+# 1. A fresh holder wallet (its secp256k1 key signs the VP and the tx)
+HOLDER_DID=$(ebsi wallet create --save | jq -r .did)
+echo "holder: $HOLDER_DID"
+
+# 2. Issue the VC on its own first — confirms it really is ES256-signed
+ebsi onboarding issue-vc --out ./onboarding-vc.jwt | jq '{alg, rtaoKid, holderDid}'
+
+# ...and read the JWT header back, independently of what the CLI reported
+node -p "JSON.stringify(JSON.parse(Buffer.from(require('fs').readFileSync('./onboarding-vc.jwt','utf8').trim().split('.')[0],'base64url')))"
+
+# 3. Onboard: trade the VC for a did-registry:invite token, insert the DID document
+ebsi onboarding onboard --vc ./onboarding-vc.jwt
+
+# 4. Confirm the DID resolves, and that a plain write token now works
+ebsi did-registry identifiers get "$HOLDER_DID"
+ebsi auth token --scope did-registry:write --save
+```
+
+Step 2 should report `"alg": "ES256"` and a `kid` whose fragment is the RTAO's
+P-256 thumbprint. Drop `EBSI_RTAO_ES256_PRIVATE_KEY` and set
+`EBSI_RTAO_ES256K_PRIVATE_KEY` instead to run the same flow ES256K-signed.
+
+Steps 2 and 3 can be collapsed into one — `onboarding onboard` mints the VC
+inline when `--vc` is omitted — but issuing it separately lets you check the
+signature before spending it.
+
+---
+
+### `auth`
+
+```
+ebsi auth token --scope <scope> [--vc <file>] [--es256k-key <hex>] [--es256-key <hex>] [--sign-alg <alg>] [--did <did>] [--save] [--spec <draft14|1.0>]
+```
+
+Obtain an EBSI access token via the OIDC4VP `vp_token` grant flow.
+
+A secp256k1 private key is required (resolved from `--es256k-key`, `EBSI_ES256K_PRIVATE_KEY`, or persisted config). When a P-256 key is also configured, `--sign-alg` picks which one signs the VP.
+
+**Options:**
+
+| Flag                    | Description                                                                                                                                                                                        |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--scope <scope>`       | **Required.** EBSI scope string — a single scope (e.g. `did-registry:write`) or several space-separated write scopes for a multi-scope token (e.g. `"did-registry:write issuers-registry:write"`). |
+| `--vc <file>`           | Path to a VC JWT file. Required for VC-scopes: `did-registry:invite`, `ledger:invoke`, `issuers-registry:invite`, `track-and-trace:authorise`.                                                     |
+| `--es256k-key <hex>`    | secp256k1 private key override (0x-prefixed hex).                                                                                                                                                  |
+| `--es256-key <hex>`     | P-256 private key override (hex), optional.                                                                                                                                                        |
+| `--sign-alg <alg>`      | Which key signs the VP when both are configured: `ES256` or `ES256K`.                                                                                                                              |
+| `--did <did>`           | DID override.                                                                                                                                                                                      |
+| `--save`                | Persist the obtained token to config (equivalent to `ebsi config set token <jwt>`).                                                                                                                |
+| `--spec <draft14\|1.0>` | Which OpenID4VP grant to speak: `draft14` (Presentation Exchange, the default) or `1.0` (final, DCQL). See below.                                                                                  |
+
+**`--spec 1.0` (DCQL grant):** speaks the OpenID4VP 1.0 (final)/DCQL `vp_token`
+shape instead of the legacy Presentation Exchange one; both are accepted by the
+server side by side. For scopes that need no explicit credential on the legacy
+grant (the seven "Combinable" scopes below), the CLI automatically mints and
+presents a self-issued `SelfAttestation` credential — `--vc` still
+takes precedence and is required as usual for the VC-bearing scopes.
+
+```sh
+ebsi auth token --scope did-registry:write --spec 1.0
+```
+
+**Scopes and VC requirements:**
+
+| Scope                       | VC required? | Combinable? | Description                        |
+| --------------------------- | ------------ | ----------- | ---------------------------------- |
+| `did-registry:write`        | No           | Yes         | Write to the DID Registry          |
+| `issuers-registry:write`    | No           | Yes         | Write to the Issuers Registry      |
+| `policies-registry:write`   | No           | Yes         | Write to the Policies Registry     |
+| `schemas-registry:write`    | No           | Yes         | Write to the Schemas Registry      |
+| `timestamp:write`           | No           | Yes         | Write timestamps                   |
+| `track-and-trace:create`    | No           | Yes         | Create Track and Trace documents   |
+| `track-and-trace:write`     | No           | Yes         | Write to Track and Trace           |
+| `did-registry:invite`       | Yes          | No          | Onboard a new DID via invitation   |
+| `ledger:invoke`             | Yes          | No          | Invoke the Ledger service directly |
+| `issuers-registry:invite`   | Yes          | No          | Invite an issuer to the registry   |
+| `track-and-trace:authorise` | Yes          | No          | Grant Track and Trace access       |
+
+**Multi-scope tokens:** the seven "Combinable" scopes above can be requested together
+in a single space-separated `--scope` value, e.g. `"did-registry:write issuers-registry:write"`. The
+resulting token authorises writes to every combined registry — the holder must
+independently qualify for each one (it's a pure AND of the individual checks, so a
+combined token never grants more than the same scopes requested separately would).
+Invite/invoke scopes (VC required) can only ever be requested alone.
+
+**Instance targeting:** any scope may be suffixed with `:<0x-address>` (e.g.
+`"track-and-trace:write:0x61c36a8d610163660E21a8b7359e1Cac0C9133e1"`) to target a specific deployed
+beacon-proxy instance of that scope's registry instead of the environment-configured
+default. `ledger write`/`ledger write-batch` do this automatically with `--auto-token`
+— the minted token is always instance-targeted at the resolved `--to` address(es), not
+just the bare family scope shown in the table above — so a token minted for one
+instance can't be reused to write to a different instance of the same registry.
+
+**`did-registry:invite` key binding:** the `VerifiableAuthorisationToOnboard` VC issued by the RTAO must carry the
+target key's RFC 7638 thumbprint in `credentialSubject.jwkThumbprint` — the Authorisation service rejects the
+token request otherwise, and the CLI checks it locally first so a mismatch fails fast with a clear message.
+Run `ebsi wallet info` to read the configured wallet's thumbprint and hand it to the RTAO before it issues the
+VC.
+
+**Examples:**
+
+```sh
+# Get a token for a write scope (no VC required)
+ebsi auth token --scope did-registry:write
+
+# Get a token and persist it
+ebsi auth token --scope did-registry:write --save
+
+# Get a single token covering two registries
+ebsi auth token --scope "did-registry:write issuers-registry:write" --save
+
+# Target a specific contract instance instead of the environment default
+ebsi auth token --scope track-and-trace:write:0x61c36a8d610163660E21a8b7359e1Cac0C9133e1
+
+# Check the wallet's key thumbprint before asking the RTAO to issue an onboard VC for it
+ebsi wallet info
+
+# Get a token for an invite scope (VC required; the VC's credentialSubject.jwkThumbprint
+# must match this wallet's thumbprint)
+ebsi auth token --scope did-registry:invite --vc ./my-credential.jwt
+
+# One-liner: set key + get + persist token
+ebsi --es256k-key 0xdeadbeef... auth token --scope did-registry:write --save
+```
+
+---
+
+### `ledger`
+
+```
+ebsi ledger call <method> [params]
+ebsi ledger block <blockNumberOrTag>
+ebsi ledger tx <hash>
+ebsi ledger read <registry> <function> <args>
+ebsi ledger write <registry> <function> <args>
+ebsi ledger batch <source>
+ebsi ledger write-batch <file>
+```
+
+Interact with the EBSI Besu node via the Ledger service JSON-RPC proxy.
+
+#### `ledger call`
+
+Send an arbitrary JSON-RPC request to the node.
+
+```sh
+ebsi ledger call eth_blockNumber
+ebsi ledger call eth_getBlockByNumber '["latest", false]'
+ebsi ledger call eth_getBalance '["0xabc...", "latest"]'
+```
+
+Options: `--id <n>` (JSON-RPC request id, default `1`).
+
+#### `ledger block`
+
+Get a block by number or tag. Shorthand for `eth_getBlockByNumber`.
+
+```sh
+ebsi ledger block latest
+ebsi ledger block 0x1e240
+```
+
+#### `ledger tx`
+
+Get a transaction by hash. Shorthand for `eth_getTransactionByHash`.
+
+```sh
+ebsi ledger tx 0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b
+```
+
+#### `ledger read`
+
+ABI-encode a registry **view/pure** function call and resolve it via `eth_call` — the
+read-only counterpart to `ledger write`. No wallet or token needed, since `eth_call` is
+served anonymously. Returns the function's outputs as an array, in declaration order.
+
+```
+ebsi ledger read <registry> <function> <args-json> [--to <address>]
+```
+
+| Argument    | Description                                                       |
+| ----------- | ----------------------------------------------------------------- |
+| `registry`  | Target registry (see table under [`ledger write`](#ledger-write)) |
+| `function`  | Smart contract view/pure function name (e.g. `getTimestamp`)      |
+| `args-json` | Function arguments as a JSON array string                         |
+
+`--to <address>` behaves exactly as it does for `ledger write` — if omitted, it falls
+back to the registry's address env var.
+
+```sh
+ebsi ledger read timestamp getTimestamp '["0xtimestampId"]' --to 0xContractAddress
+```
+
+#### `ledger write`
+
+ABI-encode a registry function call, sign an Ethereum transaction, and submit it via the Ledger service.
+
+```
+ebsi ledger write <registry> <function> <args-json> [options]
+```
+
+| Argument    | Description                                                          |
+| ----------- | -------------------------------------------------------------------- |
+| `registry`  | Target registry (see table below)                                    |
+| `function`  | Smart contract function name (e.g. `insertDidDocument`, `addIssuer`) |
+| `args-json` | Function arguments as a JSON array string                            |
+
+**Options:**
+
+| Flag                  | Description                                                                                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--to <address>`      | Contract address (0x-prefixed). If omitted, read from the registry's env var (see table below).                                                               |
+| `--token <jwt>`       | Bearer access token. Resolved from `--token`, `EBSI_ACCESS_TOKEN`, or persisted config.                                                                       |
+| `--auto-token`        | Mint a fresh access token inline via the VP flow instead of using a pre-obtained one.                                                                         |
+| `--scope <scope>`     | EBSI scope for `--auto-token`. Defaults to the registry/function's default scope, instance-targeted at the resolved `--to` address (see below).               |
+| `--vc <file>`         | VC JWT file for VC-required scopes when using `--auto-token`.                                                                                                 |
+| `--es256k-key <hex>`  | secp256k1 private key override (0x-prefixed hex).                                                                                                             |
+| `--did <did>`         | DID override.                                                                                                                                                 |
+| `--gas-limit <value>` | Advanced: manual gas limit (decimal or `0x`-prefixed hex). By default estimated from the node via `eth_estimateGas`.                                          |
+| `--gas-price <value>` | Advanced: manual gas price (decimal or `0x`-prefixed hex), forcing a legacy transaction. By default fees are derived from the node (EIP-1559 when supported). |
+
+Gas is estimated dynamically from the node by default (with 20% headroom over the raw
+`eth_estimateGas` figure, to absorb state shifting between estimation and inclusion) —
+`--gas-limit`/`--gas-price` are escape hatches for when you need to override that (e.g.
+a known gas-hungry call, or matching a specific fee for testing). If gas estimation
+fails (e.g. the call would revert), `ledger write` fails immediately with a descriptive
+error instead of signing and submitting a transaction that's likely doomed on-chain.
+
+**Known registries:**
+
+| Registry name       | Default scope             | Address env var                      |
+| ------------------- | ------------------------- | ------------------------------------ |
+| `did-registry`      | `did-registry:write`      | `DID_REGISTRY_CONTRACT_ADDRESS`      |
+| `issuers-registry`  | `issuers-registry:write`  | `ISSUERS_REGISTRY_CONTRACT_ADDRESS`  |
+| `policies-registry` | `policies-registry:write` | `POLICIES_REGISTRY_CONTRACT_ADDRESS` |
+| `schemas-registry`  | `schemas-registry:write`  | `SCHEMAS_REGISTRY_CONTRACT_ADDRESS`  |
+| `timestamp`         | `timestamp:write`         | `TIMESTAMP_CONTRACT_ADDRESS`         |
+| `track-and-trace`   | `track-and-trace:write`   | `TRACK_AND_TRACE_CONTRACT_ADDRESS`   |
+
+> **Exceptions:**
+>
+> - `did-registry`'s `insertDidDocument` onboards a _new_ DID and requires `did-registry:invite`
+>   (a VC-bearing scope, see [`auth`](#auth)), not `did-registry:write` — every other
+>   `did-registry` write function uses the default scope shown above.
+> - `track-and-trace`'s `authoriseDid` requires `track-and-trace:authorise` (VC-bearing), and
+>   `createDocument`/`commitCreateDocument` require `track-and-trace:create` — every other
+>   `track-and-trace` write function (`grantAccess`, `removeDocument`, `revokeAccess`,
+>   `writeEvent`) uses the default `track-and-trace:write` shown above.
+>
+> With `--auto-token` and no `--scope`, the CLI picks the right one automatically.
+
+With `--auto-token` and no explicit `--scope`, the minted token is always
+**instance-targeted** at the resolved `--to` address (e.g. `did-registry:invite:0xContractAddress`),
+not just the bare family scope shown above — see "Instance targeting" under
+[`auth`](#auth).
+
+**Examples:**
+
+```sh
+# Insert a DID document using a pre-obtained token (needs a did-registry:invite-scoped token,
+# with a VerifiableAuthorisationToOnboard VC bound to this wallet's key — see `auth`)
+ebsi ledger write did-registry insertDidDocument \
+  '["did:ebsi:z123", "{}", "thumbprint", "0xpubkey", true, 0, 9999999999]' \
+  --to 0xContractAddress \
+  --token eyJ...
+
+# Same, but mint the token automatically (requires a configured key and a VC file;
+# --auto-token derives the required did-registry:invite:<address> scope automatically)
+ebsi ledger write did-registry insertDidDocument \
+  '["did:ebsi:z123", "{}", "thumbprint", "0xpubkey", true, 0, 9999999999]' \
+  --to 0xContractAddress \
+  --vc ./my-credential.jwt \
+  --auto-token
+
+# Full one-liner: key + auto-token + contract address from env
+export DID_REGISTRY_CONTRACT_ADDRESS=0xContractAddress
+export EBSI_ES256K_PRIVATE_KEY=0xdeadbeef...
+ebsi ledger write did-registry insertDidDocument \
+  '["did:ebsi:z123", "{}", "thumbprint", "0xpubkey", true, 0, 9999999999]' \
+  --vc ./my-credential.jwt \
+  --auto-token
+
+# A did-registry write that's NOT insertDidDocument only needs the plain
+# did-registry:write default scope (no VC required)
+ebsi ledger write did-registry addController \
+  '["did:ebsi:z123", "0xNewControllerAddress"]' \
+  --to 0xContractAddress \
+  --auto-token
+```
+
+#### `ledger batch`
+
+Send a raw JSON-RPC **batch** request to the Besu node: an array of independent
+requests submitted under a single `Authorization` header and processed in order.
+Besu accepts at most **1024** requests per batch. An entry without an `id` is a
+JSON-RPC _notification_ — it's still processed, but gets no response entry.
+
+```
+ebsi ledger batch <source>
+```
+
+`<source>` is a path to a JSON file containing a JSON array of requests, or `-` to
+read the array from stdin. Each entry: `{"method": "...", "params": [...], "id": ...}`
+(`params` defaults to `[]`, `id` may be omitted).
+
+The Bearer token, if any is needed (e.g. the batch includes `eth_sendRawTransaction`
+entries), comes from `--token` / `EBSI_ACCESS_TOKEN` / `ebsi config set token`, same as
+`ledger call`.
+
+**Examples:**
+
+```sh
+# batch.json:
+# [
+#   {"id": 1, "method": "eth_blockNumber"},
+#   {"id": 2, "method": "eth_getBalance", "params": ["0xabc...", "latest"]}
+# ]
+ebsi ledger batch ./batch.json
+
+# Pipe a batch in from stdin
+echo '[{"id": 1, "method": "eth_blockNumber"}]' | ebsi ledger batch -
+```
+
+#### `ledger write-batch`
+
+Sign several registry writes from one wallet, under one access token, and submit them
+as a **single** JSON-RPC batch request — one round-trip instead of one per write. Each
+write is assigned a sequential nonce so they don't collide. Returns transaction
+hashes, not receipts — use `ledger tx <hash>` afterwards to check status.
+
+```
+ebsi ledger write-batch <file> [options]
+```
+
+`<file>` is a JSON array of write entries, one per transaction — the same shape as
+`ledger write`'s positional args:
+
+```json
+[
+  { "registry": "did-registry", "function": "insertDidDocument", "args": [...], "to": "0x..." },
+  { "registry": "issuers-registry", "function": "addIssuerProxy", "args": [...], "to": "0x..." }
+]
+```
+
+`to` is optional per entry and falls back to the registry's address env var, same as
+`ledger write`.
+
+**Options:** same as `ledger write` (`--auto-token`, `--scope`, `--vc`, `--key`,
+`--did`, `--gas-limit`, `--gas-price`) — `--gas-limit`/`--gas-price`, when given, apply
+to **every** entry in the batch; by default each entry's gas limit is estimated
+independently and fees are resolved once for the whole batch. Unlike `ledger write`,
+an entry whose gas estimation fails doesn't fail the whole batch — a batch entry can
+legitimately only become valid once an earlier entry in the same batch has been
+mined, so a warning is printed and a generous default gas limit is used for that
+entry instead. With `--auto-token` and no `--scope`, the CLI derives the **minimal
+multi-scope token** covering every distinct registry referenced in the batch, each
+instance-targeted at its entry's resolved contract address (e.g. a batch writing to
+`did-registry` at `0xDidContractAddress` and `issuers-registry` at
+`0xIssuersContractAddress` mints `"did-registry:write:0xDidContractAddress
+issuers-registry:write:0xIssuersContractAddress"`) — one token, one round-trip, instead of minting
+one per registry. This only works when every entry's default scope is combinable (see
+[`auth`](#auth)) — a batch containing `insertDidDocument` (which needs the
+non-combinable `did-registry:invite`) can't use `--auto-token` without an explicit
+`--scope`/`--token` covering just that one write.
+
+**Examples:**
+
+```sh
+# writes.json:
+# [
+#   { "registry": "did-registry", "function": "addController",
+#     "args": ["did:ebsi:z123", "0xNewControllerAddress"],
+#     "to": "0xDidContractAddress" },
+#   { "registry": "issuers-registry", "function": "addIssuerProxy",
+#     "args": ["did:ebsi:z123", "0xhash"], "to": "0xIssuersContractAddress" }
+# ]
+
+# Mint one multi-scope token covering both registries and submit both writes together
+ebsi --es256k-key 0xdeadbeef... ledger write-batch ./writes.json --auto-token
+```
+
+---
+
+## Read commands
+
+Every read command below (`did-registry`, `schemas-registry`, `issuers-registry`,
+`policies-registry`, `timestamp`, `track-and-trace`, `contracts-registry`) accepts a
+`--contract-address <address>` option. If omitted, it defaults to the **same
+address env var used by `ledger write`** for that registry (see the table under
+[`ledger write`](#ledger-write)) — e.g. `did-registry identifiers list` defaults to
+`DID_REGISTRY_CONTRACT_ADDRESS` if set. This keeps reads and writes pointed at the
+same contract instance within one environment, but it also means an env var set
+only to pick a signing target for `ledger write` will silently redirect reads too;
+pass `--contract-address` explicitly on a read command to override it for that call
+only. `contracts-registry` has no write path, so its `contracts`/`templates`
+sub-resources instead default from `PROXY_FACTORY_CONTRACT_ADDRESS` and
+`PROXY_TEMPLATES_REGISTRY_CONTRACT_ADDRESS` respectively (the API's own config keys for that
+domain). If none of the flag, env var, or persisted config apply, the API's own
+configured default address is used.
+
+### `did-registry`
+
+```
+ebsi did-registry identifiers list [--page-after <cursor>] [--page-size <n>] [--controller <did>]
+                                    [--verification-method-id <id>] [--verification-relationship <rel>]
+ebsi did-registry identifiers get <did> [--valid-at <date>]
+ebsi did-registry abi
+```
+
+| Command                 | Description                                                                                                                |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `identifiers list`      | List all EBSI DIDs. Supports pagination and filtering by controller, verification method id, or verification relationship. |
+| `identifiers get <did>` | Resolve a DID document. Use `--valid-at <ISO-8601>` to retrieve a historical version.                                      |
+| `abi`                   | Get the ABI of the DID Registry smart contract.                                                                            |
+
+**`identifiers list` filter options:**
+
+| Flag                                | Description                                                                                                                                  |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--controller <did>`                | Filter by controller DID.                                                                                                                    |
+| `--verification-method-id <id>`     | Filter by verification method id (e.g. `did:ebsi:z...#key-1`).                                                                               |
+| `--verification-relationship <rel>` | Filter by verification relationship: `authentication`, `assertionMethod`, `keyAgreement`, `capabilityInvocation`, or `capabilityDelegation`. |
+
+---
+
+### `schemas-registry`
+
+```
+ebsi schemas-registry schemas list [--page-after <cursor>] [--page-size <n>]
+ebsi schemas-registry schemas get <schemaId>
+ebsi schemas-registry schemas revisions <schemaId> [--page-after <cursor>] [--page-size <n>]
+ebsi schemas-registry schemas revision <schemaId> <schemaRevisionId>
+ebsi schemas-registry schemas metadata list <schemaId> <schemaRevisionId> [--page-after <cursor>] [--page-size <n>]
+ebsi schemas-registry schemas metadata get <schemaId> <schemaRevisionId> <metadataId>
+ebsi schemas-registry abi
+```
+
+| Command                                                           | Description                                         |
+| ----------------------------------------------------------------- | --------------------------------------------------- |
+| `schemas list`                                                    | List all trusted schemas on the EBSI ledger.        |
+| `schemas get <schemaId>`                                          | Get a schema by its ID.                             |
+| `schemas revisions <schemaId>`                                    | List all revisions of a schema.                     |
+| `schemas revision <schemaId> <schemaRevisionId>`                  | Get a specific revision of a schema.                |
+| `schemas metadata list <schemaId> <schemaRevisionId>`             | List metadata for a schema revision.                |
+| `schemas metadata get <schemaId> <schemaRevisionId> <metadataId>` | Get metadata for a schema revision.                 |
+| `abi`                                                             | Get the ABI of the Schemas Registry smart contract. |
+
+---
+
+### `issuers-registry`
+
+```
+ebsi issuers-registry issuers list [--page-after <cursor>] [--page-size <n>]
+ebsi issuers-registry issuers get <did>
+ebsi issuers-registry issuers attributes list <did> [--page-after <cursor>] [--page-size <n>]
+ebsi issuers-registry issuers attributes get <did> <attributeId>
+ebsi issuers-registry issuers attributes revisions <did> <attributeId> [--page-after <cursor>] [--page-size <n>]
+ebsi issuers-registry issuers attributes revision <did> <attributeId> <revisionId>
+ebsi issuers-registry issuers proxies list <did> [--page-after <cursor>] [--page-size <n>]
+ebsi issuers-registry issuers proxies get <did> <proxyId>
+ebsi issuers-registry issuers proxies content <did> <proxyId> <path>
+ebsi issuers-registry abi
+```
+
+| Command                                                        | Description                                             |
+| -------------------------------------------------------------- | ------------------------------------------------------- |
+| `issuers list`                                                 | List trusted issuers on the EBSI ledger.                |
+| `issuers get <did>`                                            | Get an issuer by DID.                                   |
+| `issuers attributes list <did>`                                | List attributes for an issuer.                          |
+| `issuers attributes get <did> <attributeId>`                   | Get an attribute for an issuer.                         |
+| `issuers attributes revisions <did> <attributeId>`             | List revisions of an issuer attribute.                  |
+| `issuers attributes revision <did> <attributeId> <revisionId>` | Get a specific revision of an issuer attribute.         |
+| `issuers proxies list <did>`                                   | List proxy data for an issuer.                          |
+| `issuers proxies get <did> <proxyId>`                          | Get a proxy for an issuer.                              |
+| `issuers proxies content <did> <proxyId> <path>`               | Get a status list credential through an issuer's proxy. |
+| `abi`                                                          | Get the ABI of the Issuers Registry smart contract.     |
+
+---
+
+### `policies-registry`
+
+```
+ebsi policies-registry policies list [--page-after <cursor>] [--page-size <n>]
+ebsi policies-registry policies get <policyName>
+ebsi policies-registry subjects list [--page-after <cursor>] [--page-size <n>]
+ebsi policies-registry subjects get <subject>
+ebsi policies-registry subjects policies <subject> [--page-after <cursor>] [--page-size <n>]
+ebsi policies-registry subjects policy <subject> <policyName>
+ebsi policies-registry abi
+```
+
+| Command                                  | Description                                            |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `policies list`                          | List all policies on the EBSI ledger.                  |
+| `policies get <policyName>`              | Get a policy by name (e.g. `VerifiableAuthorisation`). |
+| `subjects list`                          | List all subjects with assigned policies.              |
+| `subjects get <subject>`                 | Get a subject by DID.                                  |
+| `subjects policies <subject>`            | List all policies assigned to a subject DID.           |
+| `subjects policy <subject> <policyName>` | Get a specific policy assigned to a subject.           |
+| `abi`                                    | Get the ABI of the Policies Registry smart contract.   |
+
+---
+
+### `timestamp`
+
+```
+ebsi timestamp timestamps list [--page-after <cursor>] [--page-size <n>]
+ebsi timestamp timestamps get <timestampId>
+ebsi timestamp records list [--page-after <cursor>] [--page-size <n>]
+ebsi timestamp records get <recordId>
+ebsi timestamp records versions <recordId> [--page-after <cursor>] [--page-size <n>]
+ebsi timestamp records version <recordId> <versionId>
+ebsi timestamp hash-algorithms list [--page-after <cursor>] [--page-size <n>]
+ebsi timestamp hash-algorithms get <hashAlgorithmId>
+ebsi timestamp abi
+```
+
+| Command                                  | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `timestamps list`                        | List timestamps on the EBSI ledger.              |
+| `timestamps get <timestampId>`           | Get a timestamp by its ID.                       |
+| `records list`                           | List timestamp records.                          |
+| `records get <recordId>`                 | Get a timestamp record by ID.                    |
+| `records versions <recordId>`            | List all versions of a timestamp record.         |
+| `records version <recordId> <versionId>` | Get a specific version of a timestamp record.    |
+| `hash-algorithms list`                   | List supported hash algorithms for timestamping. |
+| `hash-algorithms get <hashAlgorithmId>`  | Get a hash algorithm by its ID.                  |
+| `abi`                                    | Get the ABI of the Timestamp smart contract.     |
+
+---
+
+### `track-and-trace`
+
+```
+ebsi track-and-trace documents list [--page-after <cursor>] [--page-size <n>]
+ebsi track-and-trace documents get <documentId>
+ebsi track-and-trace documents events <documentId> [--page-after <cursor>] [--page-size <n>]
+ebsi track-and-trace documents event <documentId> <eventId>
+ebsi track-and-trace documents accesses <documentId> [--page-after <cursor>] [--page-size <n>]
+ebsi track-and-trace accesses get <subject>
+ebsi track-and-trace accesses check <creator>
+ebsi track-and-trace abi
+```
+
+| Command                                  | Description                                               |
+| ---------------------------------------- | --------------------------------------------------------- |
+| `documents list`                         | List all Track and Trace documents.                       |
+| `documents get <documentId>`             | Get a document by ID.                                     |
+| `documents events <documentId>`          | List events for a document.                               |
+| `documents event <documentId> <eventId>` | Get an event for a document.                              |
+| `documents accesses <documentId>`        | List accesses for a document.                             |
+| `accesses get <subject>`                 | Get access control entries for a subject DID.             |
+| `accesses check <creator>`               | Check whether a DID is allowlisted as a document creator. |
+| `abi`                                    | Get the ABI of the Track and Trace smart contract.        |
+
+---
+
+### `contracts-registry`
+
+```
+ebsi contracts-registry contracts list [--page-after <cursor>] [--page-size <n>]
+ebsi contracts-registry contracts get <address>
+ebsi contracts-registry templates list [--page-after <cursor>] [--page-size <n>]
+ebsi contracts-registry templates get <id>
+ebsi contracts-registry abi
+```
+
+| Command                   | Description                                           |
+| ------------------------- | ----------------------------------------------------- |
+| `contracts list`          | List smart contracts in the EBSI Contracts Registry.  |
+| `contracts get <address>` | Get a contract by its hex address.                    |
+| `templates list`          | List contract templates.                              |
+| `templates get <id>`      | Get a contract template by ID.                        |
+| `abi`                     | Get the ABI of the Contracts Registry smart contract. |
+
+---
+
+## Pagination
+
+List commands that return paginated results accept these options:
+
+| Option                  | Description                                                               |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `--page-after <cursor>` | Cursor for the next page (value of `links.next` from a previous response) |
+| `--page-size <n>`       | Maximum items per page                                                    |
+
+```sh
+# First page
+ebsi did-registry identifiers list --page-size 10
+
+# Next page (use the cursor from the previous response's `links.next`)
+ebsi did-registry identifiers list --page-size 10 --page-after eyJhbGciOi...
+```
+
+## Scripting examples
+
+```sh
+# Count DIDs on the pilot network
+ebsi --env pilot --output json did-registry identifiers list | jq '.total'
+
+# Extract all trusted issuer DIDs
+ebsi --output json issuers-registry issuers list | jq -r '.items[].did'
+
+# Check health, exit 1 on failure (useful in CI)
+ebsi --output json health | jq -e '.status == "ok"'
+
+# Persist pilot as default, then query without flags
+ebsi config set env pilot
+ebsi did-registry identifiers list
+
+# End-to-end DID write: generate key, get token, add a controller to an existing DID
+ebsi wallet create --save
+ebsi auth token --scope did-registry:write --save
+ebsi ledger write did-registry addController \
+  '["did:ebsi:z123", "0xNewControllerAddress"]' \
+  --to 0xContractAddress
+
+# Same, in a single command using --auto-token
+ebsi --es256k-key 0xdeadbeef... ledger write did-registry addController \
+  '["did:ebsi:z123", "0xNewControllerAddress"]' \
+  --to 0xContractAddress \
+  --auto-token
+```
+
+## Development
+
+```sh
+# Install dependencies
+pnpm install
+
+# Regenerate API types from openapi.yaml
+pnpm --filter @europeum-ebsi/cli gen:api-types
+
+# Build
+pnpm --filter @europeum-ebsi/cli build
+
+# Run tests
+pnpm --filter @europeum-ebsi/cli test:ci
+
+# Lint
+pnpm --filter @europeum-ebsi/cli lint
+```