1---
  2title: Usage
  3sidebar_position: 3
  4---
  5
  6# Usage
  7
  8## First Launch
  9
 10On first launch, Matcha will prompt you to configure an email account. You'll need:
 11
 12- Your email address
 13- Your password (or app-specific password for Gmail/iCloud)
 14- Email provider (Gmail, iCloud, or Custom)
 15
 16## Keyboard Shortcuts
 17
 18### Main Menu
 19
 20- `↑/↓` or `j/k` - Navigate menu items
 21- `Enter` - Select option
 22- `Esc` - Go back / Exit
 23- `Ctrl+C` - Quit application
 24
 25### Inbox View
 26
 27- `↑/↓` or `j/k` - Navigate emails
 28- `←/→` or `h/l` - Switch between account tabs
 29- `Enter` - Open selected email
 30- `/` - Filter/search emails
 31- `r` - Refresh inbox
 32- `[` / `]` - Switch focus between inbox and split pane (when split pane is enabled)
 33- `d` - Delete selected email
 34- `a` - Archive selected email
 35- `v` - Enter visual mode (multi-select)
 36- `Esc` - Back to main menu
 37
 38#### Visual Mode (Multi-Select)
 39
 40Visual mode allows you to select multiple emails and perform batch operations, similar to Vim's visual mode:
 41
 42- `v` - Enter visual mode (selects current email)
 43- `↑/↓` or `j/k` - Expand/contract selection
 44- `d` - Delete all selected emails
 45- `a` - Archive all selected emails
 46- `m` - Move all selected emails to a folder
 47- `v` or `Esc` - Exit visual mode
 48
 49**Visual indicators:**
 50- `>` - Cursor position
 51- `*` - Selected email (not cursor)
 52- `>*` - Selected email with cursor
 53- Title shows: "Inbox - VISUAL (N selected)"
 54
 55**Features:**
 56- Efficient batch operations using single IMAP commands
 57- Automatic prevention of cross-account selections
 58- Works in both inbox and folder views
 59- Visual mode disabled during search/filtering for safety
 60
 61### Email View
 62
 63- `↑/↓` or `j/k` - Scroll email content
 64- `r` - Reply to email
 65- `d` - Delete email
 66- `a` - Archive email
 67- `Tab` - Focus attachments
 68- `Esc` - Back to inbox
 69- `i` - Toggle images
 70
 71### Attachment View (when focused)
 72
 73- `↑/↓` or `j/k` - Navigate attachments
 74- `Enter` - Download and open attachment
 75- `Tab` or `Esc` - Back to email body
 76
 77### Composer
 78
 79- `Tab` / `Shift+Tab` - Navigate fields
 80- `Enter` -
 81  - On "From" field: Select account (if multiple)
 82  - On "Attachment" field: Open file picker
 83  - On "Send" button: Send email
 84- `↑/↓` - Navigate contact suggestions (when typing in "To" field)
 85- `Esc` - Save draft and exit
 86
 87## CLI Commands
 88
 89Matcha includes several CLI subcommands that work without launching the TUI.
 90
 91### Send Email
 92
 93Send an email directly from the command line:
 94
 95```bash
 96matcha send --to user@example.com --subject "Hello" --body "Hi there"
 97```
 98
 99This is useful for scripts, automation, and [AI agent integration](./Features/AI_AGENTS.md). See the full [CLI reference](./Features/CLI.md) for all options.
100
101### Update
102
103Check for updates and install the latest version:
104
105```bash
106matcha update
107```
108
109This command will:
110
1111. Check for the latest release on GitHub
1122. Detect your installation method (Homebrew, Snap, or binary)
1133. Update using the appropriate method
114
115### Gmail OAuth2
116
117Manage Gmail OAuth2 authorization:
118
119```bash
120matcha gmail auth <email>     # Authorize a Gmail account
121matcha gmail token <email>    # Print a fresh access token
122matcha gmail revoke <email>   # Revoke stored tokens
123```