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
• Attribution

Installation

Shell (macOS / Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/agentmail-to/agentmail-cli/releases/latest/download/agentmail-cli-installer.sh | sh

PowerShell (Windows)

powershell -ExecutionPolicy ByPass -c "irm https://github.com/agentmail-to/agentmail-cli/releases/latest/download/agentmail-cli-installer.ps1 | iex"

npm

npm install -g agentmail-cli

Or run 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_API_KEY="<your token>"
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, table, yaml, csv, jsonl, raw, http.

Without --format, output (including errors) is table when stdout is a terminal and json when it is piped or redirected — so scripts and agents get JSON by default. Pass --human to keep the interactive rendering when piping to a pager, and --format json to pin JSON in a terminal.

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

# Keep the human rendering even when piped
agentmail <resource> <method> --human | less

# Machine-readable catalog of every operation (same as --schema)
agentmail --help --format json | jq '.operations | length'

Shell completion

Generate shell completion scripts:

agentmail completion <bash|zsh|fish|powershell>

Attribution

Built on fern-cli-sdk, Copyright Fern, licensed under the Apache License 2.0.