Command-line interface (CLI)

cirrux is the command-line interface for Cirrux. Use it to browse mailboxes and threads, read and organize emails, manage labels and filters, compose and send drafts, download attachments, read and change calendar events, look up contacts, manage Drive files, folders and public links, and read, edit and comment on Cirrux Docs documents, straight from your shell or from an AI coding assistant like Claude Code or Codex.

Install

Install with Homebrew

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

brew install cirrux.info/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 login --no-browser   # on a headless or remote machine: sign in with a code on another device
cirrux whoami               # show the current user + workspace
cirrux doctor               # check the install, sign-in and coding agent setup
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. If you logged in before a command group existed (Drive, Docs, calendar, contacts, sending), log in again once to grant its scopes.

Use it with Claude Code

Install the agent skill

The CLI ships with an agent skill, a bundled guide that teaches Claude Code, Codex 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. An interactive cirrux login offers to do this for you when it finds an agent that is not connected yet.

cirrux skill install            # ~/.agents/skills/cirrux, linked from ~/.claude/skills/cirrux
cirrux skill install --project  # the same under the current directory, to check into a repo
cirrux skill uninstall          # remove it again
cirrux skill print              # preview the skill without installing

There is one copy of the skill, in ~/.agents/skills/cirrux, where Codex and other Agent Skills tools look for it. Claude Code gets a link to it from ~/.claude/skills/cirrux. Pass --force to replace a skill at that path that the CLI did not install. After you upgrade the CLI, the installed skill is updated to match. 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. Set a different one with --co-author <name> or the cirrux.info_AUTHOR environment variable.

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, labels, filters, attachments, calendars, events, contacts, Drive files and folders, and documents are identified by opaque UUIDs. List or search to find them rather than constructing them by hand. Run cirrux <command> --help for every flag.

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

cirrux mailbox labels create <uuid> --name <name>Create a custom label

cirrux mailbox labels update / delete <uuid> <label-uuid>Rename (--name) or delete a custom label

cirrux mailbox addresses list <uuid>List a mailbox's addresses (aliases), the primary one first

cirrux mailbox addresses create <uuid> <address>Add an alias to a mailbox

cirrux mailbox addresses update / delete <uuid> <address>Deactivate (--deactivate, --activate), make primary (--primary) or delete an alias

cirrux mailbox filters list / getList a mailbox's filter rules, or show one in full

cirrux mailbox filters create <uuid>Create a filter rule (--name, --condition-ast, --actions, --priority, --status, --stop-processing)

cirrux mailbox filters update / delete <uuid> <filter-uuid>Change or delete a filter rule

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, --label, --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 inbox, archive, trash or junk (--type) or to a custom label (--label-uuid)

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

cirrux email labels add <uuid> --type auto_archiveArchive an inbox email automatically after 30 days

Draft

cirrux draft create --mailbox-uuid <uuid>Create a draft from a .eml file (--file), stdin, or a markdown body (--markdown with --subject, --to, --cc, --bcc)

cirrux draft create ... --in-reply-to <email-uuid>Make the draft a reply; markdown replies quote the original unless --no-quote-original

cirrux draft send <uuid>Send a draft immediately (needs the email.send scope)

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)

Calendar

cirrux calendar listList the calendars you can see

cirrux calendar events list <calendar-uuid>Events in a window, repeating ones expanded (--today, --on, --from, --to, --days, --timezone)

cirrux calendar events create <calendar-uuid>Create an event (--title, --start, --end, --all-day, --recurrence, --attendee, --location)

cirrux calendar events update <calendar-uuid> <event-id>Change an event, or one occurrence of a repeating one

cirrux calendar events delete <calendar-uuid> <event-id>Delete an event, or cancel one occurrence (--yes to skip the prompt)

Guests added with --attendee are emailed an invite, and deleting an event emails them a cancellation. An event UUID changes the whole event; an occurrence ID from events list changes just that occurrence.

Contacts

cirrux.infontacts addressbooksList your addressbooks

cirrux.infontacts list <addressbook-uuid>List the contacts in one addressbook

cirrux.infontacts search <query>Search by name, company or email address (--addressbook-uuid)

cirrux.infontacts get <uuid>Show a contact with its email addresses and phone numbers

Drive

cirrux drive list [folder-uuid]List folders and files (omit for the root)

cirrux drive get <uuid>Show file metadata (name, content type, size)

cirrux drive download <uuid>Download to stdout or a file (--output; --json for base64url)

cirrux drive upload [folder-uuid] --file <path>Upload a file, 2 GB max (--name, --content-type)

cirrux drive replace <uuid> --file <path>Replace a file's contents, keeping its UUID (--content-type)

cirrux drive rename <uuid> <new-name>Rename a file

cirrux drive move <uuid>Move a file into a folder (--to) or to the root (--root)

cirrux drive trash <uuid>Move a file to the trash (reversible)

cirrux drive delete <uuid>Permanently delete a file

Folders

cirrux drive folder create --name <name>Create a folder (--parent, --color)

cirrux drive folder get / rename <uuid>Show or rename a folder

cirrux drive folder move <uuid>Move a folder (--to or --root)

cirrux drive folder trash / delete <uuid>Trash or permanently delete a folder and everything in it

Sharing

cirrux drive share get <uuid>Show who it is shared with and its public link (--folder for a folder)

cirrux drive share create / revoke <uuid>Create or revoke a public download link (--folder for a folder)

The CLI encrypts uploads and decrypts downloads on your machine, in the same format the web app uses, and streams large files in chunks. Sharing with people is done in the Drive app; the CLI can read those grants and manage public links.

Docs

cirrux docs listYour documents and the ones shared with you (--query, --trashed)

cirrux docs get <document>Show a document's title, owner, your role and link

cirrux docs read <document>Print it as markdown, suggestions marked inline (--comments adds the open threads)

cirrux docs replace <document> <find> <with>Replace quoted text inside one block

cirrux docs insert <document> [markdown]Insert markdown --after or --before a quote, or --at start or end

cirrux docs delete-text <document> <find>Delete quoted text

cirrux docs write <document>Replace the whole document with markdown

cirrux docs edit <document> --operations <file>Several edits as one, from JSON

cirrux docs attach <document> <file>Attach a file or image, and place it with --after, --before or --at

cirrux docs download <document> <attachment>Download an attachment's file (--output)

cirrux docs comments add <document> <body> --on <quote>Comment on quoted text, or on the whole document without --on

cirrux docs comments reply|edit|resolve|reopen|deleteReply, edit your words, resolve, reopen or delete a comment

cirrux docs suggestions accept|reject|withdrawAccept or reject a suggestion (editor role), or withdraw your own

cirrux docs create --title "Plan"Create an empty document

cirrux docs rename <document> <title>Rename a document

cirrux docs trash <document>Move a document to Trash (deleted after 30 days)

cirrux docs restore <document>Take a document out of Trash

A document can be given as its UUID or as its docs.cirrux.info link. Edits quote the text they change, exactly as cirrux docs read prints it, and need the editor role. Add --suggest to replace, insert, delete-text or edit to suggest the change instead (with --comment to say why); suggesting and commenting need the commenter role. Cirrux Docs is in preview, open to accounts that have been given early access.

Skill

cirrux skill installInstall the agent skill and connect Claude Code and Codex

cirrux skill uninstallRemove the skill and its agent links

cirrux skill printPrint the bundled skill contents

Other

cirrux doctorCheck the install, sign-in and coding agent setup

cirrux feedback [message]Send feedback to the Cirrux team (or pipe it on stdin)

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)
6	Rate limited, after the CLI’s own retries ran out

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:trash / in:spam / in:snoozed / in:starred
label:Receipts                  label:"Project X"
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.

label: finds your own labels by name. Case doesn’t matter, and you can write spaces as hyphens (label:project-x). A name matches that label in every mailbox you search. You can also pass --label with a label name or UUID, for example cirrux thread search invoice --label Receipts.

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