Command-line interface (CLI)

cirrux is the command-line interface for Cirrux. Use it to authenticate, browse mailboxes and threads, read and organize emails, compose drafts, and download attachments — straight from your shell or from an AI coding assistant like Claude Code.

Install

Install with Homebrew

The CLI is distributed through our Homebrew tap. Install it with:

brew install cirrux-co/tap/cirrux

Confirm it’s installed and check the version with cirrux --version. Run cirrux --help at any time, or cirrux <command> --help for a specific command — the CLI is self-documenting and always lists its current flags.

Authenticate

cirrux login     # browser-based OAuth
cirrux whoami    # show the current user + workspace
cirrux logout    # sign out of the current workspace

Commands that hit the API exit with code 4 when you’re not logged in — run cirrux login to authenticate.

Use it with Claude Code

Install the agent skill

The CLI ships with an agent skill— a bundled guide that teaches Claude Code (and other skill-aware assistants) how to use cirrux: authentication, output modes, the full command tree, and common workflows. Install it once and your assistant can reach for the CLI on its own.

cirrux skill install            # installs to ~/.claude/skills/cirrux/
cirrux skill install --project  # installs to ./.claude/skills/cirrux/ (this repo)
cirrux skill print              # preview the skill without installing

Install to ~/.claude/skills to make it available everywhere, or use --project to check it into a specific repository. Pass --force to overwrite an existing copy. Once installed, ask your assistant something like “show me the latest unread thread in my inbox” and it’ll use the CLI.

When run from inside Claude Code, the CLI automatically tags every change with the co-author claude, so you can tell which actions came from your assistant in the activity feed.

How commands work

Commands follow a cirrux <noun> <verb> structure (for example cirrux thread list). Data is always written to stdout and diagnostics to stderr, so you can safely pipe output between commands. Mailboxes, threads, emails, and attachments are identified by opaque UUIDs — list or search to find them rather than constructing them by hand.

Mailbox

cirrux mailbox listList the mailboxes you can access

cirrux mailbox get <uuid>Show metadata for a single mailbox

cirrux mailbox labels list <uuid>List a mailbox's system and custom labels

Thread

cirrux thread list <mailbox-uuid>List threads in a mailbox (--label, --limit, --cursor)

cirrux thread get <uuid>Show a thread with all of its non-deleted emails

cirrux thread search <query>Search threads (--mailbox-uuid, --limit, --cursor)

Email

Read & search

cirrux email get <uuid>Show email metadata (subject, from, to, labels)

cirrux email content <uuid> bodyRendered HTML body

cirrux email content <uuid> rawFull MIME message (pipe to a .eml file)

cirrux email search <query>Search individual emails across mailboxes

Organize

cirrux email read / unread <uuid>Mark as read or unread

cirrux email flag / unflag <uuid>Star or unstar

cirrux email archive / unarchive <uuid>Archive or move back to the inbox

cirrux email trash / untrash <uuid>Move to trash or restore to the inbox

cirrux email spam / unspam <uuid>Mark as spam or restore to the inbox

cirrux email move <uuid>Move to a location (--type) or custom label (--label-uuid)

cirrux email labels add / remove <uuid>Add or remove a custom label (--label-uuid)

Draft

cirrux draft create --mailbox-uuid <uuid>Create a draft from a .eml file, stdin, or --markdown

cirrux draft send <uuid>Send a draft immediately

cirrux draft delete <uuid>Delete a draft

Attachment

cirrux attachment get <uuid>Show metadata (filename, content type, size)

cirrux attachment download <uuid>Download raw bytes to stdout (--json for base64url)

Skill

cirrux skill installInstall the agent skill into Claude Code

cirrux skill printPrint the bundled skill contents

Output modes

Every data-producing command supports three output modes, so the same command works for reading at the terminal, parsing in a script, or piping into the next command.

Flag	Output	Use it when
(default)	Human-readable text	Reading output at the terminal
--json	Structured JSON	Parsing fields in a script
--quiet	Bare identifiers, one per line	Piping UUIDs into the next command

Exit codes

Commands return predictable exit codes so scripts can branch on them without parsing error text.

0	Success
1	General or unexpected failure
2	Bad arguments or usage
3	Resource not found
4	Not logged in or permission denied
5	Resource already exists (conflict)

Search

Query operators

cirrux thread search and cirrux email search share the same engine — the difference is whether results are grouped by conversation or by individual message. Scope a search to one mailbox with --mailbox-uuid whenever you can; an unscoped search spans every mailbox you can access.

Operators are ANDed by default; prefix any operator with a hyphen to negate it.

from:alice@example.com          to: / cc: / bcc:
subject:"quarterly review"      body:invoice
is:read / is:unread             is:starred / is:unstarred
is:replied                      has:attachment
in:inbox / in:sent / in:drafts / in:archive / in:snoozed / in:starred
after:2026-01-01 before:2026-04-01
"phrase match"                  -from:noreply@example.com

Quote the whole query when it contains spaces or shell characters, e.g. cirrux thread search "from:alice is:unread". Results exclude trash and spam automatically.

Pipe commands together

Because --quiet prints bare UUIDs, you can chain commands to build small workflows. This reads the body of every email in the latest inbox thread:

mb=$(cirrux mailbox list --quiet | head -1)
thread=$(cirrux thread list "$mb" --label inbox --limit 1 --quiet)
cirrux thread get "$thread" --quiet | while read email_uuid; do
  cirrux email content "$email_uuid" body
done