agentmail-cli

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.