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- `d` - Delete selected email
33- `a` - Archive selected email
34- `Esc` - Back to main menu
35
36### Email View
37
38- `↑/↓` or `j/k` - Scroll email content
39- `r` - Reply to email
40- `d` - Delete email
41- `a` - Archive email
42- `Tab` - Focus attachments
43- `Esc` - Back to inbox
44- `i` - Toggle images
45
46### Attachment View (when focused)
47
48- `↑/↓` or `j/k` - Navigate attachments
49- `Enter` - Download and open attachment
50- `Tab` or `Esc` - Back to email body
51
52### Composer
53
54- `Tab` / `Shift+Tab` - Navigate fields
55- `Enter` -
56  - On "From" field: Select account (if multiple)
57  - On "Attachment" field: Open file picker
58  - On "Send" button: Send email
59- `↑/↓` - Navigate contact suggestions (when typing in "To" field)
60- `Esc` - Save draft and exit
61
62## CLI Commands
63
64Matcha includes several CLI subcommands that work without launching the TUI.
65
66### Send Email
67
68Send an email directly from the command line:
69
70```bash
71matcha send --to user@example.com --subject "Hello" --body "Hi there"
72```
73
74This is useful for scripts, automation, and [AI agent integration](./Features/AI_AGENTS.md). See the full [CLI reference](./Features/CLI.md) for all options.
75
76### Update
77
78Check for updates and install the latest version:
79
80```bash
81matcha update
82```
83
84This command will:
85
861. Check for the latest release on GitHub
872. Detect your installation method (Homebrew, Snap, or binary)
883. Update using the appropriate method
89
90### Gmail OAuth2
91
92Manage Gmail OAuth2 authorization:
93
94```bash
95matcha gmail auth <email>     # Authorize a Gmail account
96matcha gmail token <email>    # Print a fresh access token
97matcha gmail revoke <email>   # Revoke stored tokens
98```