CLI

The Tether CLI lets you set up your agent, verify your agent's identity, and debug the challenge-response flow — all from the terminal.

Install

npm install -g tether-name-cli

Or use without installing:

npx tether-name-cli verify

Commands

tether init

Interactive setup wizard. Walks you through configuring your agent ID, private key path, and optionally generates a new RSA-2048 key pair.

tether init

This saves your configuration to ~/.tether/config.json.

If you choose to generate keys, it creates files in ~/.tether/keys/ (outside your current working directory) to reduce accidental git commits:

• ~/.tether/keys/<agent>.private.pem (private key, chmod 600)
• ~/.tether/keys/<agent>.public.pem (public key, for registering with Tether)

If you manually set a key path inside a git repository, tether init prints a safety warning.

tether verify

Perform a full identity verification — requests a challenge, signs it, submits proof, and displays the result.

tether verify

# Machine-readable output
tether verify --json

tether status

Show your current configuration — agent ID (masked) and key file path.

tether status

tether status --json

tether challenge

Request a new challenge code from the Tether API and print it.

tether challenge

tether sign <challenge>

Sign a challenge string with your private key and print the proof.

tether sign "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

tether check <code>

Check the status of a challenge by its code.

tether check "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

tether check "a1b2c3d4-e5f6-7890-abcd-ef1234567890" --json

tether agent create <name>

Create a new agent. Requires a bearer token (JWT or API key).

tether agent create "my-bot" --description "My helpful bot"

Assign a verified domain to the agent:

tether agent create "my-bot" --domain-id "domain-id-here"

tether agent create "my-bot" --json

Returns the agent's ID, name, and a registration token (save it — it can't be retrieved later).

tether agent list

List all agents associated with your bearer token.

tether agent list

tether agent list --json

tether agent delete <id>

Delete an agent by its agent ID.

tether agent delete "agent-id-here"

tether agent delete "agent-id-here" --json

tether agent update <id>

Update which identity appears when that agent is verified.

# Show a verified domain
tether agent update "agent-id-here" --domain-id "domain-id"

# Revert to account email
tether agent update "agent-id-here" --show-email

tether agent update "agent-id-here" --domain-id "domain-id" --json

tether agent keys <agentId>

List key lifecycle entries (active, grace, revoked) for an agent.

Requires bearer auth (JWT or API key).

tether agent keys "agent-id"
tether agent keys "agent-id" --json

tether agent rotate-key <agentId>

Rotate an agent key. Requires bearer auth (JWT or API key) plus step-up verification via either: - --step-up-code, or - --challenge + --proof

tether agent rotate-key "agent-id" \
  --public-key "BASE64_SPKI_PUBLIC_KEY" \
  --grace-hours 24 \
  --step-up-code 123456

tether agent revoke-key <agentId> <keyId>

Revoke a specific key. Requires bearer auth (JWT or API key) plus step-up verification via either: - --step-up-code, or - --challenge + --proof

tether agent revoke-key "agent-id" "key-id" \
  --reason "compromised" \
  --step-up-code 123456

Tip

The CLI flag/env name is still --api-key / TETHER_API_KEY. For key lifecycle endpoints in automation, prefer --challenge + --proof step-up with your API key.

tether domain list

List all domains registered to your account. Requires a bearer token (JWT or API key).

tether domain list

tether domain list --json

Shows each domain's name, verification status, and ID. Use the domain ID with tether agent create --domain-id to assign a domain to an agent.

Configuration

The CLI resolves configuration in this order (first wins):

1. CLI flags — --agent-id, --key-path, --api-key
2. Environment variables — TETHER_AGENT_ID, TETHER_PRIVATE_KEY_PATH, TETHER_API_KEY
3. Config file — ~/.tether/config.json (created by tether init)

Global Flags

Flag	Description
--agent-id <id>	Override agent ID
--key-path <path>	Override private key file path
--api-key <key>	Bearer token for management operations (API key or JWT)
--verbose	Enable debug output
--json	Machine-readable JSON output (on supported commands)

Example Workflows

Verification

# 1. Set up your agent
tether init

# 2. Check your config
tether status

# 3. Verify your identity
tether verify

# 4. Debug: manually request and sign a challenge
tether challenge
tether sign "the-challenge-code"
tether check "the-challenge-code"

Agent Management

# Create an agent
tether agent create "my-bot" --description "My helpful assistant"

# Create an agent with a verified domain
tether domain list                              # find the domain ID
tether agent create "my-bot" --domain-id "abc123"

# Update identity display
tether agent update "agent-id" --show-email
tether agent update "agent-id" --domain-id "abc123"

# List all agents
tether agent list

# Key lifecycle
tether agent keys "agent-id"
tether agent rotate-key "agent-id" --public-key "BASE64_SPKI_PUBLIC_KEY" --step-up-code 123456
tether agent revoke-key "agent-id" "key-id" --reason "compromised" --step-up-code 123456

# Delete an agent
tether agent delete "agent-id"

# List domains
tether domain list

Agent and domain management commands require a bearer token. API keys work for standard CRUD and key lifecycle endpoints; key lifecycle mutations (rotate-key, revoke-key) also require step-up verification. Set your bearer token via --api-key, the TETHER_API_KEY environment variable, or in your config file.

Links

• npm
• GitHub