Lib.rs

Cardinal is a command-first terminal workspace for email and calendar.

Cardinal is built for people who live on the keyboard: operators, developers, and long-time terminal users who want mail and calendar control without mouse-heavy workflows.

Core rule:

Workspace displays.
Prompt acts.

Cardinal is not a GUI mail clone. It is a focused TUI product where mail, calendar, agenda, invites, and search share one consistent command language.

Why Cardinal

Cardinal starts local-first:

Mail server      -> external sync -> local Maildir -> Cardinal
Calendar server  -> external sync -> local vdir/.ics -> Cardinal
Cardinal         -> SMTP sender
Cardinal         -> .ics/vdir writer

This model keeps failure modes visible and operationally simple:

• your data stays in local files
• sync stays explicit through your existing tools
• mutations stay command-driven and testable

Direct IMAP/CalDAV/JMAP integrations are intentionally deferred.

What the product does today

Current implementation includes:

• Terminal UI shell with normal mode + command mode
• Local Maildir reading and safe local mail actions (:archive, :delete, :spam, :move, :mark, :undo)
• Local vdir/.ics reading and safe calendar actions (:event new, :event edit, :event delete, :event move)
• Compose/reply flow with explicit :send confirm
• Invite bridge from text/calendar email parts
• Unified search workspace for mail and events
• External sync command integration (:sync)
• Runtime config validation, logging hooks, crash-safe terminal recovery
• Man page/completions generation and packaging scaffolds

Milestones 0 through 10 are implemented. Current work focuses on release and distribution hardening.

Installation

Install from crates.io:

cargo install --locked cardinal-app

One-line installer (commit-pinned):

curl -fsSL "https://radicle.noumena.mx/raw/rad:z3Yt8Pd4KwEqVuvGPM1E6XfgKFdvk/0b506079b90bd5a4642bcfab250f03a15f17abca/install.sh" | bash

One-line installer (latest main commit resolved via API):

RID="rad:z3Yt8Pd4KwEqVuvGPM1E6XfgKFdvk"
HOST="https://radicle.noumena.mx"
SHA="$(curl -fsSL "$HOST/api/v1/repos/$RID/commits" | grep -o '"id":"[0-9a-f]\{40\}"' | head -n1 | cut -d'"' -f4)"
curl -fsSL "$HOST/raw/$RID/$SHA/install.sh" | bash

Install from local source checkout:

cargo install --path crates/cardinal-cli --locked

Full install docs:

• docs/INSTALL.md
• docs/PACKAGING.md

Quick start

Launch:

cardinal

Try the core flow:

:list inboxes
:list mail
:calendar today
:agenda week

Use real local data:

CARDINAL_MAILDIR="$HOME/.local/share/mail/personal" \
CARDINAL_VDIR="$HOME/.local/share/calendars" \
cardinal

Load multiple mail accounts from one parent root:

CARDINAL_MAILDIR="$HOME/.local/share/mail" \
CARDINAL_VDIR="$HOME/.local/share/calendars" \
cardinal

Import profile env files from existing terminal setups (experimental):

make export-neomutt
source .cardinal-local/neomutt/mxroute.env
cardinal

Also supported:

make export-aerc
source .cardinal-local/aerc/personal.env
cardinal

make export-mbsync
source .cardinal-local/mbsync/mxroute-local.env
cardinal

make export-khal
source .cardinal-local/khal/work.env
cardinal

Fish users (example):

make export-aerc
source .cardinal-local/aerc/personal.fish
cardinal

Enable send:

CARDINAL_SMTP_HOST="smtp.example.com" \
CARDINAL_SMTP_FROM="you@example.com" \
CARDINAL_SMTP_USERNAME="you@example.com" \
CARDINAL_SMTP_PASSWORD_CMD='pass show mail/example' \
cardinal

Enable sync:

CARDINAL_SYNC_MAIL_CMD="mbsync -a" \
CARDINAL_SYNC_CALENDAR_CMD="vdirsyncer sync" \
cardinal

Validate config:

cardinal config validate

UI theme and splash:

CARDINAL_THEME="cardinal-dark" CARDINAL_SPLASH="1" cardinal

Supported themes: cardinal-dark, cardinal-light (aliases: dark, light).

AI and automation

Cardinal supports machine-readable command parsing for agent workflows:

CARDINAL_LOG_STDERR=0 cardinal parse --format json ':search from:alice'

Use this JSON contract to gate execution by isa.safety and keep all mutations explicit command actions.

Reference:

• docs/guides/ai-agent-workflows.md

Command examples

:list inboxes
:list mail
:open 4
:reply
:send
:send confirm
:archive
:delete
:spam
:undo
:calendar today
:agenda week
:event new
:event edit
:event delete
:invite accept
:search from:alice
:sync

Documentation

• Product docs entry:

  • docs/README.md
  • docs/START_HERE.md
  • docs/USAGE.md
  • docs/guides/ai-agent-workflows.md
  • docs/SUMMARY.md

• Governance:

  • docs/DECISIONS.md
  • docs/RFC_PROCESS.md
  • rfcs/README.md
  • adrs/README.md

Development checks

make fmt
make check
make test
make clippy
make docs-check
make ci

Status

Cardinal is in release hardening for real-world use by keyboard-first users. The local-first command model and milestone feature set are implemented; current work is focused on installation UX, distribution, and operational polish.