fastmail-cli

A command-line client for Fastmail: manage email, contacts, calendars, masked email, and file storage via JMAP, CalDAV, and WebDAV.

中文文档

Install

# From source
go install github.com/biao29/fastmail-cli/cmd/fastmail@latest
go install github.com/biao29/fastmail-cli/cmd/fm@latest

# Or build locally
make build

Both fastmail and fm are identical binaries (alias for shorter typing).

Authentication Setup

fastmail-cli uses two credential types to access different Fastmail protocols:

Credential Type	Protocol	CLI Features	Where to Create
API Token	JMAP	Email, contacts, masked email	Manage API tokens
App Password	CalDAV / WebDAV	Calendar, files	Manage app passwords

Most users only need an API Token to cover core features. Calendar and file support will migrate to unified authentication in a future release.

Create an API Token (Recommended)

┌──────────────────────────────────────────────────────┐
│  Fastmail Web → ⚙ Settings → Privacy & Security     │
│    → Manage API tokens → New API token               │
│                                                       │
│  ┌────────────────────────────────────────────┐       │
│  │  ☑ Email                                   │       │
│  │    urn:ietf:params:jmap:mail               │       │
│  │    → mail list/show/move/archive/search    │       │
│  │                                            │       │
│  │  ☑ Email submission                        │       │
│  │    urn:ietf:params:jmap:submission         │       │
│  │    → mail send/reply/forward               │       │
│  │                                            │       │
│  │  ☑ Masked Email                            │       │
│  │    fastmail.com/dev/maskedemail            │       │
│  │    → masked list/create/enable/disable     │       │
│  │                                            │       │
│  │  ☑ Contacts and contact groups             │       │
│  │    urn:ietf:params:jmap:contacts           │       │
│  │    → contact list/show/search/groups       │       │
│  │                                            │       │
│  │          [ Generate API token ]            │       │
│  └────────────────────────────────────────────┘       │
│                                                       │
│  Token will be shown in fmu1-XXXXXXXX format          │
│  ⚠ Displayed only once — copy it immediately          │
└──────────────────────────────────────────────────────┘

Permission recommendations:

• Read-only testing: Check Email + Contacts + Masked Email only
• Full usage: Check all (including Email submission for sending)
• Minimal permissions: Check only the features you need

Create an App Password (for Calendar/File Users)

If you need calendar or file commands, create an additional App Password:

Settings → Privacy & Security
  → Manage app passwords → New app password
  → Access: select "DAV (CardDAV/CalDAV/WebDAV)"

App Passwords are used for CalDAV/WebDAV Basic Auth and have a different format than API Tokens.

CLI Login

# Step 1: JMAP authentication (email, contacts, masked email)
fastmail auth login --token fmu1-XXXXXXXX

# Step 2: CalDAV/WebDAV authentication (calendar, files) — optional
fastmail auth add-dav --password <your-app-password>

Verify:

fastmail auth status    # View auth status (shows JMAP + DAV)
fastmail me             # View account info
fastmail doctor         # Health check (JMAP + CalDAV + WebDAV connectivity)

Credential Storage

┌─────────────────────────────────────────────────┐
│  Credential Storage Priority                     │
│                                                  │
│  1. FASTMAIL_TOKEN env var   (CI/scripting)      │
│     ↓ not set                                    │
│  2. System keychain          (macOS Keychain /   │
│     ↓ unavailable             Linux Secret Svc)  │
│  3. File storage             (~/.config/fastmail/│
│                               credentials.json)  │
└─────────────────────────────────────────────────┘

• CI/Automation: Set FASTMAIL_TOKEN env var — no auth login needed
• Force file storage: Set FASTMAIL_NO_KEYRING=1
• Credential file permissions: Automatically set to 0600 (owner read/write only)

Security Recommendations

• Create a dedicated App Password for the CLI — don't reuse passwords from other apps
• Only check the permissions you need (principle of least privilege)
• Periodically review active App Passwords in Fastmail settings
• When no longer needed, run fastmail auth logout and revoke the App Password in Fastmail settings

Quick Start

# Authenticate (see detailed steps above)
fastmail auth login --token fmu1-XXXXXXXX

# View inbox
fastmail mail list

# Read an email
fastmail mail show <id>

# Send an email
fastmail mail send --to user@example.com --subject "Hello" --body "Hi there"

# View calendars
fastmail calendar list

# Manage files
fastmail file list

Commands

Group	Commands
auth	login, logout, status, token
mail	list, show, send, reply, forward, move, archive, trash, flag, snooze, search
mailbox	list, show, create, update, delete
contact	list, show, create, update, delete, search, groups
calendar	list, show, events, add-event
file	list, show, upload, download, delete, mkdir
masked	list, create, enable, disable, delete
me	Show current user info
doctor	Health checks
skill	Print or install AI agent skill
commands	JSON command catalog

Output Formats

fastmail mail list                 # Auto: styled for TTY, JSON for pipes
fastmail mail list --json          # Full JSON envelope with breadcrumbs
fastmail mail list --md            # Markdown tables
fastmail mail list --quiet         # Data only, no envelope
fastmail mail list --ids-only      # One ID per line
fastmail mail list --count         # Count only
fastmail mail list --jq '.data[]'  # Built-in jq filtering
fastmail mail list --agent         # Machine-optimised for AI agents

Configuration

Priority: CLI flags > environment variables > local config > global config > defaults.

# Global config
~/.config/fastmail/config.json

# Per-project config
.fastmail/config.json

Environment Variables

• FASTMAIL_TOKEN — API token (overrides stored credentials)
• FASTMAIL_NO_KEYRING — Force file-based credential storage
• FASTMAIL_SESSION_URL — Override JMAP session URL
• FASTMAIL_CALDAV_URL — Override CalDAV URL
• FASTMAIL_WEBDAV_URL — Override WebDAV URL

AI Agent Integration

# Install skill for AI agents
fastmail skill install

# Print the embedded SKILL.md
fastmail skill

Supports Claude Code (.claude-plugin/), OpenCode, and the shared ~/.agents/skills/ convention.

Development

make build          # Build both binaries
make test           # Run unit tests
make test-race      # Run with race detector
make lint           # vet + format check

License

MIT