Quick Start

The AI-First Approach

Pontius is designed for AI assistants to do the heavy lifting. The setup process works like this:

• Your AI runs commands — license activation, verification, knowledge base setup
• You only type passwords — they go straight to your system keychain, never exposed to the AI

This is the core security model: your AI manages your inbox without ever seeing your credentials.

Start the Setup

Tell your AI assistant:

Run pontius setup and help me get Pontius configured.

Your AI will see a complete guide with every step marked as either:

• 🤖 AI runs — commands the AI executes directly
• 🔐 You type — password entry only (you do this in your terminal)
• ✓ Verify — AI confirms each step worked

What Happens During Setup

1. License Activation

Your AI checks your license status and activates if needed:

# AI runs this to check status
$ pontius license
# If not activated, AI runs with your key
$ pontius activate XXXX-XXXX-XXXX-XXXX
License activated successfully.

2. App Password Creation

Your AI will guide you to create an app password in your email provider's settings. This is a special password just for Pontius — your main password stays secure.

For Gmail, you'll go to myaccount.google.com/apppasswords. For other providers, see our provider guides.

3. Add Your Email Account

This is the one step you do yourself. Run the Pontius TUI:

$ pontius

Then:

1. Select Add Account
2. Choose your provider (gmail, outlook, etc.)
3. Enter your display name
4. Enter your email address
5. Paste your app password (it won't display — that's normal)
6. Wait for "Account connected!"

4. AI Verifies Everything Works

Your AI confirms the connection by listing your emails:

$ pontius list
 UID    FROM                      SUBJECT
 37801  [email protected]          Weekly standup notes
 37800  [email protected]       Your ticket has been updated
 37799  [email protected]       This week in tech

5. Knowledge Base Setup

Your AI initializes the knowledge base — the system that makes Pontius smarter over time:

$ pontius knowledge init
Creating knowledge base structure...
  ✓ contacts/    - People you email
  ✓ templates/   - Reusable responses
  ✓ rules/       - Per-account behavior
  ✓ policies/    - Hard constraints
  ✓ patterns/    - Auto-action triggers
  ✓ blitz/       - Session preferences
Knowledge base ready!

Setup Complete

That's it. Your AI handled license activation, guided you through account setup, verified the connection, and initialized the knowledge base. You only typed one password.

Start Your First Blitz

Now for the fun part. Tell your AI:

Run pontius blitz, let's clear my inbox. Stabilizers on.

Stabilizers on means the AI will ask before taking any action — perfect for learning how you like to handle different types of email. Once you trust it, switch to auto mode.

Your AI will:

1. List your inbox
2. Categorize emails (needs response, noise, needs your input)
3. Draft responses for your approval
4. Archive/organize as you direct
5. Learn your patterns for next time

Quick Command Reference

Your AI can run pontius help anytime, but here are the essentials:

# Core workflow
pontius list                      # List inbox
pontius read <uid>                # Read an email
pontius reply <uid> "message"     # Reply
pontius archive <uids>            # Archive (done with it)
pontius move <uids> "folder"      # Organize
# Starting sessions
pontius blitz                     # AI email session prompt
pontius setup                     # Setup guide (what you just did)
pontius help                      # Full command reference
# Verification
pontius license                   # Check license
pontius aliases                   # List send-from addresses
pontius knowledge status          # Check knowledge base

Next Steps

• Claude Code Setup — Configure CLAUDE.md for seamless integration
• The Stabilizers Method — Understand the trust-building framework
• Knowledge Base — How Pontius learns your patterns
• CLI Reference — Complete command documentation