CLI Guide
Install and use the sam command-line tool for managing SecureAgentMail.
CLI Guide
The sam CLI provides a fast way to manage inboxes, messages, policies, and credits
from the terminal.
Installation
# macOS / Linux
curl -sSL https://secureagentmail.com/install.sh | sh
# Or build from source
git clone https://github.com/secureagentmail/cli.git
cd cli
make buildAuthentication
# Interactive login (prompts for API key)
sam auth login
# Or use environment variable
export SAM_API_KEY="sam_live_your_key_here"
# Or pass as flag
sam --api-key sam_live_your_key_here inbox list
# Check auth status
sam auth status
# Remove stored credentials
sam auth logoutCredentials are stored at ~/.secureagentmail/credentials with 0600 permissions.
Commands
Inboxes
# List all inboxes
sam inbox list
# Create a new inbox
sam inbox create --name "Support Bot" --slug support --level standard
# Get inbox details
sam inbox info supportMessages
# List messages for an inbox
sam messages list support
# Filter by status
sam messages list support --status withheld
# Get message details
sam messages get <message-id>
# Get message with security analysis
sam messages get <message-id> --show-analysis
# Release a withheld message
sam messages release <message-id>Send email
# Send with flags
sam send support --to [email protected] --subject "Hello" --body "Message body"
# Pipe body from stdin
echo "Message body" | sam send support --to [email protected] --subject "Hello"Policies
# List all policies
sam policies listCredits
# Check credit balance
sam credits
# Purchase additional credits
sam credits buy --amount 1000Account management
# Sign up for a new account (no browser required)
sam signup --org "My Company" --email [email protected]
# Run diagnostics
sam doctorShell completion
# Bash
sam completion bash > /etc/bash_completion.d/sam
# Zsh
sam completion zsh > "${fpath[1]}/_sam"
# Fish
sam completion fish > ~/.config/fish/completions/sam.fishOutput formats
All commands support --format json for machine-readable output:
sam inbox list --format json
sam credits --format jsonUse --quiet to suppress non-essential output (useful in scripts):
sam messages release <id> --quietDiagnostics
Run sam doctor to check your setup:
[✓] API Key: API key found
[✓] Key Format: Valid format (environment: live)
[✓] Connectivity: API reachable at https://secureagentmail.com/api/v1
[✓] Authentication: API key is valid
[✓] Plan & Credits: Plan: developer | Credits used: 500/50000 | Remaining: 49500
[✓] CLI Version: v1.0.0 (darwin/arm64)Environment variables
| Variable | Description |
|---|---|
SAM_API_KEY | API key for authentication |
SAM_API_URL | Override API base URL (default: https://secureagentmail.com/api/v1) |