CLI Commands Reference

Complete reference for all Pontius CLI commands. Use these commands directly or let your AI assistant call them.

Two Ways to Use Pontius

TUI Mode: Run pontius with no arguments to launch the interactive terminal interface. Great for account setup and manual email browsing.

CLI Mode: Run individual commands like pontius list for AI integration. This is where Pontius shines — giving AI tools programmatic access to your inbox.

Quick Reference

Run pontius help in your terminal for a token-efficient command reference. This output is designed for both humans and AI — always up-to-date and comprehensive.

First Time Setup?

Run pontius setup for an AI-assisted setup guide. It walks your AI assistant through helping you configure accounts, create app passwords, and verify everything works.

Command Categories

Email Operations

Search, read, reply, send, and manage emails.

Command	Description
`pontius list`	List recent emails in your inbox
`pontius search <query>`	Search emails (supports --folder, --days, --from)
`pontius read <uid>`	Read a specific email by UID (supports --folder)
`pontius reply <uid> "message"`	Reply to an email
`pontius send <to> "subject" "body"`	Send a new email (supports --attach for files)
`pontius archive <uids>`	Archive one or more emails
`pontius move <uids> "folder"`	Move emails to a folder/label
`pontius unsubscribe <uid>`	Unsubscribe from newsletter (one-click when available)

Full email operations documentation →

Folder Management

Work with Gmail labels and IMAP folders.

Command	Description
`pontius folders`	List all available folders/labels
`pontius folder create "name"`	Create a new folder/label
`pontius folder delete "name"`	Delete a folder/label

Full folder documentation →

Email Aliases & Domains

Send from multiple email addresses, manage catch-all domains, and watch addresses.

Command	Description
`pontius aliases`	List all configured aliases
`pontius alias add <email>`	Add a new alias
`pontius alias config <email>`	Configure alias SMTP settings
`pontius alias name <email> "name"`	Set display name for alias
`pontius alias remove <email>`	Remove an alias
`pontius domains`	List catch-all domains
`pontius domain add <domain>`	Add a catch-all domain
`pontius domain remove <domain>`	Remove a catch-all domain
`pontius watch`	List watch addresses (receive-only)
`pontius watch add <email>`	Add a watch address
`pontius watch remove <email>`	Remove a watch address

Full alias, domain & watch documentation →

Account Management

Manage email accounts and settings.

Command	Description
`pontius account info`	Show current account details
`pontius account set-name "name"`	Set your display name
`pontius account set-label "label"`	Set account label (shown in Pontius)

Full account documentation →

Invoicing

Generate and send professional invoices with company presets.

Command	Description
`pontius invoice <to> "product" <amount>`	Generate an invoice
`pontius invoice setup`	Interactive company setup wizard
`pontius invoice company list`	List company presets
`pontius invoice company add <name>`	Add a company preset
`pontius invoice company edit <id>`	Edit company details
`pontius invoice logo <id> <path>`	Set company logo
`pontius invoice list`	List generated invoices
`pontius invoice show <number>`	Show invoice details
`pontius invoice send <number>`	Send an existing invoice

Full invoicing documentation →

Cross-Device Sync

Encrypted export and import of your configuration.

Command	Description
`pontius sync export [file]`	Export config to encrypted file
`pontius sync import <file>`	Import config (with confirmation)
`pontius sync import <file> --merge`	Merge imported data with local
`pontius sync import <file> --force`	Overwrite without confirmation

Full sync documentation →

Licensing

Manage your Pontius license.

Command	Description
`pontius activate <key>`	Activate license on this device
`pontius license`	Show current license status
`pontius deactivate`	Remove device from license
`pontius buy`	Open purchase page

Activation documentation →

Knowledge Base

Manage your AI knowledge base.

Command	Description
`pontius knowledge init`	Create knowledge base folder structure
`pontius knowledge migrate`	Migrate from flat files to folders
`pontius knowledge status`	Show knowledge base status

Knowledge base documentation →

AI Commands

Commands designed specifically for AI assistant integration.

Command	Description
`pontius blitz`	Output AI prompt for email session
`pontius help`	Token-efficient command reference
`pontius setup`	AI-assisted first-time setup guide

Learn about AI-first design →

The Blitz Command

Run pontius blitz to get a complete AI prompt that explains both modes (stabilizers for learning, auto for autonomous), key commands, knowledge base structure, and workflow guidelines. Perfect for starting an email session with your AI.

Bulk Actions

Commands that accept <uids> support multiple email selection:

# Single email
pontius archive 37788
# Comma-separated list
pontius archive 37788,37789,37790
# Range (inclusive)
pontius archive 37788-37793
# Mixed (combine any of the above)
pontius archive 37788,37790-37795,37800

Utility Commands

Updates and maintenance.

Command	Description
`pontius update`	Show update instructions
`pontius rollback`	Rollback to the previous version
`pontius help`	Show help

Global Options

Option	Description
`help`	Show help (run: `pontius help`)
`version`	Show Pontius version

Output Format

Pontius outputs are designed to be both human-readable and AI-parseable. The output is concise to minimize token usage when used with AI tools.

$ pontius list
 UID    FROM                      SUBJECT
 37801  [email protected]          Weekly standup notes
 37800  [email protected]       Your ticket has been updated
$ pontius archive 37801
Moved email 37801 to "[Gmail]/All Mail"
$ pontius send [email protected] "Hello" "Test message"
Sent.
$ pontius send [email protected] "Your Ticket" "See attached" --attach ~/ticket.pdf
Sent with attachment: ticket.pdf (245 KB)