duta

A retro-themed TUI/CLI email tool for humans and AI agents.

duta (Sanskrit for "messenger") is a Claude Code–style terminal app for sending email. It runs in two modes from the same binary:

• Interactive TUI — launch duta with no args to compose, browse drafts, and view send history in a retro-themed terminal UI.
• Non-interactive CLI — run duta send --to ... --subject ... --body ... --json (and similar commands) for scripts and AI agents.

Status

v0.4.0 — Beta. Interfaces may shift before v1.0; breaking changes will land behind major-version bumps per semver. See CHANGELOG.md for what's shipped and docs/roadmap.md for what's next.

Quickstart

Requires Node 20 LTS or newer.

npm install -g @sathirar/duta   # global install (recommended)
duta                            # launch TUI

Or run on demand without installing:

npx @sathirar/duta

On first launch the TUI opens the onboarding wizard. Pick a transport (SMTP, Resend, or Gmail), fill in the required fields, and press ^S to save — duta writes them to ~/.duta/.env. After that you land on the main menu: Compose, Drafts, History, Help, Settings.

Keys: ↑↓ move, Enter open, Tab next field, ^S save (onboarding), ^O save draft / ^X send (compose), Esc back, q quit. The Help screen has a full keybindings reference.

Want to hack on it instead? See Dev setup below.

For agents / scripts

Every command accepts --json and returns structured output. Exit codes (see below) are stable, so scripts can branch on them. See docs/agents.md for a deeper integration guide.

# One-shot send
duta send \
  --to [email protected] \
  --subject "Hello" \
  --body "Sent from an agent" \
  --json

# Send with attachments (-a is repeatable)
duta send --to [email protected] -s "Report" -b "see attached" \
  -a ./report.pdf -a ./notes.txt --json

# Inspect recent history
duta history list --json

# Persist a config value (same file the TUI edits)
duta config set SMTP_HOST smtp.gmail.com

Config values resolve from (in order): process env → <cwd>/.env → <dataDir>/.env (default ~/.duta/.env). The TUI Settings screen and duta config set both write to <dataDir>/.env.

Features

• Pluggable transports: SMTP, Resend, and Gmail API (OAuth refresh-token).
• Plain-text email with To / CC / BCC, single configured profile.
• File attachments via duta send --attach <path> (repeatable). Send-only — drafts/history don't yet persist them.
• Local drafts and send history (SQLite at ~/.duta/duta.db).
• Lightweight update check on TUI launch — pings npm once a day, shows ↑ vX.Y.Z available under the logo when a newer release exists. Disabled in CLI/agent mode; kill entirely with DUTA_NO_UPDATE_CHECK=1.
• Config via environment variables / .env, editable in the TUI Settings screen.
• Retro TUI in Ink + React; first-run onboarding wizard for new users.
• Dual-mode binary: TUI for humans, JSON output and stable exit codes for agents.

CLI exit codes

| Code | Meaning | | ---- | ------------------------------------------------------- | | 0 | Success | | 1 | Generic error (unexpected) | | 2 | Usage error (bad args / missing required opts) | | 3 | Config error (missing / invalid env, unknown transport) | | 4 | Validation error (message failed schema) | | 5 | Transport error (SMTP / Resend send failed) | | 6 | Storage error (db open / migration failed) | | 7 | Not found (draft / history / config key) |

Dev setup

git clone https://github.com/sathirabr/duta.git
cd duta
npm install
npm run typecheck
npm run lint
npm test
npm run build

Project structure

src/
  cli/        # CLI entry (non-interactive mode + TUI launcher)
  tui/        # Ink + React components
  core/
    transport/  # Transport interface + SMTP/Resend implementations
    storage/    # SQLite drafts + history
tests/        # Vitest
docs/         # Scope, architecture notes
.github/      # Issue/PR templates + CI

Contributing

See CONTRIBUTING.md. This project uses Conventional Commits and automated releases via semantic-release.

License

MIT © sathirabr