cardinal-app 0.1.4

![Cardinal](cardinal.png)

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:

```text
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:

```text
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:

```bash
cargo install --locked cardinal-app
```

One-line installer (commit-pinned):

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

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

```bash
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:

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

Full install docs:

- [docs/INSTALL.md](docs/INSTALL.md)
- [docs/PACKAGING.md](docs/PACKAGING.md)

## Quick start

Launch:

```bash
cardinal
```

Try the core flow:

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

Use real local data:

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

Load multiple mail accounts from one parent root:

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

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

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

Also supported:

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

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

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

Fish users (example):

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

Enable send:

```bash
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:

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

Validate config:

```bash
cardinal config validate
```

UI theme and splash:

```bash
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:

```bash
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](docs/guides/ai-agent-workflows.md)

## Command examples

```vim
: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/README.md)
  - [docs/START_HERE.md](docs/START_HERE.md)
  - [docs/USAGE.md](docs/USAGE.md)
  - [docs/guides/ai-agent-workflows.md](docs/guides/ai-agent-workflows.md)
  - [docs/SUMMARY.md](docs/SUMMARY.md)

- Governance:
  - [docs/DECISIONS.md](docs/DECISIONS.md)
  - [docs/RFC_PROCESS.md](docs/RFC_PROCESS.md)
  - [rfcs/README.md](rfcs/README.md)
  - [adrs/README.md](adrs/README.md)

## Development checks

```bash
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.