AgentMail CLI

Command-line interface for the AgentMail API.

Table of contents

• Installation
• Authentication
• Quick start
• Usage
• Documentation
• Advanced
  • Common flags
  • Environment variables
  • Output formats
  • Shell completion

Installation

Install the CLI globally via npm:

npm install -g agentmail-cli

Or run it directly without installing:

npx agentmail-cli --help

Build from source

If you prefer to build from source, install the Rust toolchain and run:

cargo build --release
./target/release/agentmail --help

Authentication

Set the following environment variable(s) before using the CLI:

export AGENTMAIL_TOKEN="<your token>"

A .env file in the working directory is also supported — the CLI auto-loads it on startup.

Quick start

List available commands:

agentmail --help

Call an API endpoint:

agentmail <resource> <method>

Run agentmail <resource> --help to see available methods for a resource.

Usage

Every API resource appears as a subcommand (e.g. agentmail <resource> <method>). Run agentmail <resource> --help to see available methods.

Provide request parameters as flags or as JSON:

agentmail <resource> <method> --json '{"key": "value"}'

Documentation

See reference.md for the full command reference.

Advanced

Common flags

These flags are available on every operation:

Flag	Description
--dry-run	Validate the request locally and print the HTTP request without sending it
--json <JSON|->	Supply a request body as JSON (or - to read stdin)
--params <JSON>	Merge extra parameters as JSON (overrides individual flags)
--format <json|table|yaml|csv>	Output format (default json)
--output <PATH>	Write binary responses to a file
--base-url <URL>	Override the API base URL
--page-all	Auto-paginate and stream results as NDJSON
--page-limit <N>	Max pages to fetch when auto-paginating (default 10)
-q, --quiet	Suppress stdout output on success (errors still go to stderr)

Environment variables

Variable	Description
AGENTMAIL_BASE_URL	Override the API base URL
AGENTMAIL_CA_BUNDLE	Path to PEM file with extra trust roots (or SSL_CERT_FILE)
AGENTMAIL_INSECURE=1	Skip TLS verification (debugging only)
AGENTMAIL_PROXY	HTTP(S) proxy URL
AGENTMAIL_TIMEOUT_SECS	Total request timeout in seconds

Standard environment variables (HTTPS_PROXY / HTTP_PROXY / NO_PROXY / SSL_CERT_FILE) are also honored.

Output formats

Use the global --format flag to control output. Supported values: json (default), table, yaml, csv.

# Pipe JSON output through jq
agentmail <resource> <method> --format json | jq

# Machine-readable catalog of every operation
agentmail --help --format json | jq 'length'

Shell completion

Generate shell completion scripts:

agentmail completion <bash|zsh|fish|powershell>