TollRelay

CLI

npx @tollrelay/cli init registers the organisation, sends the sign-in link, and offers the first pass.

npx @tollrelay/cli init --region eu --handle acme

Install

The npx line above runs the command once. To keep it, install the package. It adds the trlay command.

npm i -g @tollrelay/cli

Commands

trlay init --region <eu|us> --handle <handle> [--name <name>] [--email <email>] [--label <label>] [--no-identity]

Register the organisation, send the sign-in link, and offer the first pass.

trlay login [--region <eu|us>] [--email <email>]

Sign in over the device grant, print the code, and store the session.

trlay pass create --label <label> --org <org>

Create a pass under an organisation. Makes its key on this device, keeps the private half at ~/.trlay/keys/<mid>.json and registers only the public half.

trlay pass revoke <mid>

Revoke a pass.

trlay pass token <mid>

Mint the interim token for a pass.

trlay pass list [--limit <n>] [--cursor <c>]

List the signed-in organisation's passes.

trlay pass edge <mid> on|off

Set whether a pass's agent announces itself to sites, from its next pass.

trlay identities create --label <label> --org <org>

The same as pass create.

trlay mandates set <org>/<agent> | <agent> | <mid> --usd-per-day <usd> [--usd-per-call-max <usd>] [--sellers-allow <a,b>] [--sellers-deny <a,b>] [--rails <x402,mpp>] [--requires-key-tier <hardware|service>]

Set a pass's spending limit. Name the pass as acme/research-agent, as research-agent in the signed-in organisation, or by its mid.

trlay limits set <org>/<agent> | <agent> | <mid> --usd-per-day <usd> [--usd-per-call-max <usd>] [--sellers-allow <a,b>] [--sellers-deny <a,b>] [--rails <x402,mpp>] [--requires-key-tier <hardware|service>]

The same as mandates set, in plain words.

trlay mandates propose <mid> --usd-per-day <usd> [--usd-per-call-max <usd>] [--budget <usd>] [--sellers-allow <a,b>] [--sellers-deny <a,b>] [--rails <x402,mpp>] [--not-before <iso>] [--not-after <iso>] [--requires-key-tier <hardware|service>]

Propose a new version of a pass's open spending limit, for someone to sign off.

trlay mandates versions <mid> [--limit <n>] [--cursor <c>]

List a pass's open spending limit versions, newest first.

trlay mandates sign <mid> <version> [--yes]

Review a proposed version and sign it off. Needs trlay login first.

trlay mandates refuse <mid> <version> [--yes]

Review a proposed version and refuse it. Needs trlay login first.

trlay keys list <mid> [--limit <n>] [--cursor <c>]

List a pass's devices, with where each key is held and its state.

trlay keys approve <mid> <fingerprint> [--yes]

Review a device waiting for approval and approve it. Needs trlay login first.

trlay keys revoke <mid> <fingerprint> [--yes]

Review a device and revoke it. The check refuses it at once. Needs trlay login first.

trlay record [--month <YYYY-MM>] [--limit <n>] [--cursor <c>] [--csv] [--resolve <file>]

Read the history. --csv walks every page and writes it as CSV. --resolve reads a local list of { name, key } and shows the name of each person who asked. A line names the device that signed it, as hardware, a key service or a file key, with the start of its fingerprint.

trlay trust evaluate (--did <did> | --credential <vc> | --envelope <json>) --seller <seller> --endpoint <endpoint> --amount-usd <usd> --rail <x402|mpp> [--settlement-ref <ref>]

Run a test call against the check a seller runs before serving.

trlay verifiers keys --label <label> [--id <id>] [--test] [--out <path>]

Mint a seller key. Founder-keyed. Prints the key once. With --out the key goes to the file and the screen shows its id, prefix and last four.

trlay verifiers revoke --id <verifier id> --key-id <key id> --reason <compromised|replaced|stopped>

Revoke a seller key by its id. Founder-keyed. The check refuses it within a minute. A revocation is permanent.

trlay verifiers revoke --key-file <path|-> [--reason <compromised|replaced|stopped>]

Revoke the seller key you hold. Reads the key from a file or from standard input, never from an argument, and needs no sign-in.

trlay staff activate <handle> --reason "<text>" [--yes]

TollRelay staff only. Move an organisation from sandbox to live, after showing its age and verification and asking you to confirm.

trlay staff deactivate <handle> --reason "<text>" [--yes]

TollRelay staff only. Move an organisation from live back to sandbox.

trlay --version

Print this build's version. With --json, also the contract date it sends.

Every command takes --json for a machine-readable answer.

Exit codes

  • 0: done.
  • 1: the API answered a problem, or did not answer.
  • 2: the command was used wrongly, and nothing was sent.
  • 3: signup is not open yet. TollRelay is opening to a few companies first: write to hello@tollrelay.com.

Seller keys

A seller key is vk_live_ or vk_test_, then 64 lowercase hex characters, then 8 lowercase hex characters of checksum: 80 characters in all. The checksum is the CRC-32 of everything before it (the IEEE polynomial, as zlib computes it).

The last four characters TollRelay keeps for a key are the checksum's last four, so they are not random.

The check refuses a key whose checksum fails before it reads the registry. A key minted before the checksum is 72 characters, verifies by its hash as before and does not match the pattern.

A scanner matches this pattern:

vk_(live|test)_[0-9a-f]{72}

Credentials

A credential comes from one of, in this order:

  1. --api-key
  2. TRLAY_API_KEY
  3. TRLAY_TOKEN
  4. ~/.trlay/credentials.json

This build talks to api.trlay.dev against the contract's documented shapes. It has not been verified against a live deployment.