xin

name	xin
description	Use xin CLI to manage JMAP email (Fastmail-first). Covers search, read, send, drafts, labels, and automation.
allowed-tools	Bash(xin:*)

xin CLI

Agent-first JMAP CLI for Fastmail email management.

Generated from xin CLI v0.1.3

Prerequisites

The xin command must be available on PATH. To check:

xin --version

If not built, see: https://github.com/onevcat/xin

Quick Configuration (Fastmail)

# Store Fastmail API token (this bootstraps a minimal config if missing)
xin auth set-token fmu1-xxxxx

Best Practices

Output Formats

• Default output is stable JSON (agent-first contract)
• Use --plain only for quick human confirmation (not a stability contract)
• Never parse --plain output in automation

Agent pattern: inbox → jq → act

# Get inbox items (per-email)
xin messages search "in:inbox" --max 200 \
  | jq -r '.data.items[] | [.emailId, (.subject // "")] | @tsv'

# Example: pick only subjects matching "invoice" and archive them
xin messages search "in:inbox" --max 200 \
  | jq -r '.data.items[]
    | select((.subject // "") | test("invoice"; "i"))
    | .emailId' \
  | xargs -n 50 sh -c 'xin batch modify "$@" --remove inbox --add archive' _

Query Syntax

xin supports a query sugar DSL (NOT Gmail-compatible):

# Mailbox
in:<mailbox>            # resolves by role, then name (e.g. inbox, trash, junk)

# Basic operators
from:<text>
to:<text>
cc:<text>
bcc:<text>
subject:<text>
text:<text>

# State
seen:true|false         # $seen keyword
flagged:true|false      # $flagged keyword

# Attachments + time
has:attachment
after:<YYYY-MM-DD>
before:<YYYY-MM-DD>

# Boolean
-term                   # NOT (e.g., -in:trash)
or:(a | b)              # OR

Quote multi-term queries: xin search "from:github subject:release".

Destructive Operations

Use --dry-run first for destructive commands:

xin batch modify <emailId> --remove inbox --add archive --dry-run

File-based Input

For long content, read from file using @/path:

xin send --to [e-mail] --subject "Hello" --text @/tmp/body.txt

Available Commands

xin search      # Search (thread-like by default)
xin messages    # Per-email search commands
xin get         # Get a single email
xin thread      # Thread operations
xin attachment  # Download an attachment
xin url         # Print webmail URL(s) (Fastmail-only)
xin archive     # Archive emails
xin read        # Mark emails as read
xin unread      # Mark emails as unread
xin trash       # Move emails to trash
xin batch       # Batch operations
xin inbox       # Inbox-zero helpers
xin labels      # Labels (mailboxes) operations
xin mailboxes   # Mailboxes operations (alias of labels)
xin identities  # Identities operations
xin send        # Send an email
xin reply       # Reply to an email by emailId (JMAP Email id)
xin drafts      # Drafts operations
xin history     # History / changes
xin watch       # Watch for email changes (polling Email/changes; NDJSON stream)
xin config      # Config file operations
xin auth        # Credential helpers

Reference Documentation

• High-level overview: commands.md

• search - Search (thread-like by default)

• messages - Per-email search commands

• get - Get a single email

• thread - Thread operations

• attachment - Download an attachment

• url - Print webmail URL(s) (Fastmail-only)

• archive - Archive emails

• read - Mark emails as read

• unread - Mark emails as unread

• trash - Move emails to trash

• batch - Batch operations

• inbox - Inbox-zero helpers

• labels - Labels (mailboxes) operations

• mailboxes - Mailboxes operations (alias of labels)

• identities - Identities operations

• send - Send an email

• reply - Reply to an email by emailId (JMAP Email id)

• drafts - Drafts operations

• history - History / changes

• watch - Watch for email changes (polling Email/changes; NDJSON stream)

• config - Config file operations

• auth - Credential helpers

For common workflows and examples, see common-tasks.

For JSON output schema, see JSON Schemas.

Discovering Options

To see available subcommands and flags, run --help:

xin --help
xin search --help
xin inbox --help
xin inbox do --help

Environment Variables

• XIN_TOKEN or XIN_TOKEN_FILE - Bearer token
• XIN_BASE_URL or XIN_SESSION_URL - JMAP endpoint
• XIN_BASIC_USER and XIN_BASIC_PASS - Basic auth (alternative to Bearer)

Provider Notes

• xin url is Fastmail-only - generates Fastmail web URLs
• Other providers will return xinNotImplemented for Fastmail-specific features
• xin is RFC-first; provider limitations surface as JMAP errors