CLI reference: mt

Install

The install scripts detect the operating system and architecture, download the release archive, verify the Ed25519 signature on the release's SHA256SUMS with the Mutual Trust release key built into the script, check the archive's SHA-256 against the signed list, and install mt. No runtime, package manager or administrator rights are required.

Both installers verify the release signature before installing. install.sh checks the Ed25519 signature (SHA256SUMS.sig) when OpenSSL 3 is present, and otherwise the ECDSA P-256 signature (SHA256SUMS.p256.der.sig) with any openssl, including the LibreSSL that macOS ships. Set MT_REQUIRE_SIGNATURE=1 to refuse an install that cannot be verified. install.ps1 verifies the P-256 signature using .NET.

Packages and archives

Every release is published at https://mutualtrust.io/downloads/mt/VERSION/; /downloads/mt/latest holds the current version.

A container image (distroless, nonroot, mt renew --watch by default, state in the /var/lib/mutualtrust volume) builds from services/mt/Dockerfile: docker build -f services/mt/Dockerfile -t mt services.

Verify a download

The release public key is published at mutualtrust.io/downloads/mt-release.pub and is built into mt self-update and both install scripts. With OpenSSL 3:

Global options

Flags may appear before or after positional arguments. mt help COMMAND (or mt COMMAND --help) prints a command's flags.

Upgrading from the JavaScript CLI. When the default home has no identity and ~/.mt does, mt copies ~/.mt/workload and the gateway pairings into the default home on first use and leaves a MIGRATED.txt note in ~/.mt; the old files are left in place for anything that still reads them. With --home ~/.mt (or MT_HOME), mt uses that directory as it is: both CLIs read and write the same files.

mt gateway

Starts the sample Orders API and runs the enforcer, which is built into mt, in proxy mode in front of it. It pairs the gateway (first run only) and keeps running. mt quickstart is an alias.

• On first run the enforcer generates a P-256 gateway key, prints a pairing code and approval URL, and waits until the code is approved in the portal. The approved credential and pinned policy-verification key are saved to DIR/gateway/gateway-state.json (mode 0600); later runs reuse them.
• A self-signed localhost server certificate is created at DIR/gateway/server.pem; mt call trusts it automatically.
• The gateway refreshes policy every 15 to 17 seconds, sends signed acknowledgments and receipts, and logs every decision with its request ID, verdict, reason, principal and policy revision.
• Ctrl-C flushes pending receipts and stops. To pair again, delete gateway-state.json.

mt gateway pair --print-credentials pairs an enforcer that runs elsewhere (the Cloudflare Worker) and prints its credentials as JSON for wrangler secret bulk; the pairing code goes to stderr. To enforce in front of a real API, see the standalone mTLS proxy guide or the guide for your gateway under Gateways.

mt enroll

Generates a P-256 key, sends a CSR and proof of possession, polls while signing is pending, and writes the identity. See Enrollment.

mt renew

The new key, certificate, chain and identity.json are committed together: each file is staged and synced, a journal marks the commit, and the files are renamed into place, so a crash never leaves a key next to the wrong certificate. The hook receives MT_CERT_FILE, MT_CHAIN_FILE, MT_KEY_FILE (file store), MT_ROOT_FILE, MT_CERTIFICATE_ID and MT_SERIAL. Only when the hook succeeds does mt confirm the reload, signed by the new key; if the hook fails, the confirmation is held back and the next run (or the next --watch cycle) retries the hook and the confirmation. See Renewal.

mt call

Presents DIR/workload/chain.pem with the key from the identity's key store, and deliberately adds a spoofed x-mt-principal header so you can confirm the gateway strips it. Prints the verdict, request ID, policy revision and body.

mt status

Exits 5 when no identity is enrolled, and 1 when the certificate has expired.

mt service

Installs mt renew --watch (default) or mt gateway as a system service that starts at boot and restarts on failure, using this binary, the current --home and, when given, --api. Arguments after -- are appended to the service command.

The .deb and .rpm packages ship equivalent mt-renew and mt-enforcer units that read MT_API and MT_ON_RENEW from /etc/default/mt (or /etc/sysconfig/mt).

mt enforcer

The enforcer is built into mt: mt enforcer MODE takes the same commands and flags as the standalone mt-enforcer binary (proxy, envoy-grpc, forward-auth, lambda, run --config FILE, pair, credentials, bundle, healthcheck, version), described in the gateway guides.

The standalone mt-enforcer remains available for containers, Lambda and gateway sidecars: mt enforcer install, the mt-enforcer_* release archives, or services/enforcer/Dockerfile.

mt adapt

The integration adapter runtime is built in too: mt adapt COMMAND is mt-adapt COMMAND (list, capabilities, assess, inspect, desired, plan, render, apply, verify, rollback, observe, report, approval). See Integration adapters.

mt discover

Read-only migration discovery: does a connection depend on publicly issued client certificates? Sectigo published 10 February 2027 as the final cutoff for clientAuth in newly issued publicly trusted Sectigo SSL/TLS certificates, and inventory and renewal timing decide the effect on each deployment. Every finding is labelled verified, inferred or unknown and names its source. The workflow, delegation and the meaning of each label are in Migration discovery.

Captured text (headers, certificate fields, CA names, configuration comments) is untrusted: control and markup characters are stripped, and text that reads like instructions is withheld and reported in an untrusted_instructions finding without being printed. Secrets are always redacted; --redact-hosts also masks internal hostnames, private addresses, upstreams and file paths, and is on by default with --submit.

mt version, mt self-update

mt self-update downloads SHA256SUMS and SHA256SUMS.sig for the release, verifies the Ed25519 signature with the release key built into the running binary, checks the archive's SHA-256 against the signed list, and replaces the executable atomically. It refuses to touch an install owned by a package manager (/usr/bin/mt from the .deb or .rpm, Homebrew, Scoop or winget) and names the command to use instead; --force overrides.

Key storage

The store is recorded in identity.json, so mt renew and mt call find the key without flags. mt renew --key-store STORE moves an identity to another store with its next key.

Files

The layout is the one the JavaScript CLI uses, so either CLI reads the other's files.

JSON output

With --json, enroll, renew, call, status, discover, service --dry-run, enforcer which, version and self-update print one JSON document on stdout. Errors print {"error": {"message", "exit_code", "status", "code", "request_id"}}. mt renew --watch --json prints one document per renewal.

Exit codes

mt enforcer MODE and mt adapt return the exit codes of mt-enforcer and mt-adapt.

JavaScript CLI (optional)

A single-file JavaScript build of the CLI, mt.mjs (SHA-256), remains available for environments that already standardize on Node.js 20 or later. It covers gateway, enroll, renew, call, status and enforcer install with the same wire formats and files, and keeps its state in ~/.mt. It has no service installer, reload hooks, key stores, built-in enforcer or self-update: use the native mt unless you need it.