---
title: CLI
description: npx @tollrelay/cli init registers the organisation, sends the sign-in link, and offers the first pass.
canonical: https://tollrelay.com/docs/cli
lastmod: 2026-10-28
---

# CLI

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

```sh
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.

```sh
npm i -g @tollrelay/cli
```

## Commands

```sh
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.

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

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

```sh
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.

```sh
trlay pass revoke <mid>
```

Revoke a pass.

```sh
trlay pass token <mid>
```

Mint the interim token for a pass.

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

List the signed-in organisation's passes.

```sh
trlay pass edge <mid> on|off
```

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

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

The same as pass create.

```sh
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.

```sh
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.

```sh
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.

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

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

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

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

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

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

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

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

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

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

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

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

```sh
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.

```sh
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.

```sh
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.

```sh
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.

```sh
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.

```sh
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.

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

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

```sh
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 `--api-key`, `TRLAY_API_KEY`, `TRLAY_TOKEN`, `~/.trlay/credentials.json`, in that order.

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