Folder Management

Folders vs Labels

Gmail uses "labels" instead of folders. Pontius treats them interchangeably — when you create a "folder" in Gmail, it creates a label. Other IMAP providers use traditional folders.

Listing Folders

View all available folders and labels:

$ pontius folders
INBOX
[Gmail]/All Mail
[Gmail]/Drafts
[Gmail]/Important
[Gmail]/Sent Mail
[Gmail]/Spam
[Gmail]/Starred
[Gmail]/Trash
Work
Work/Projects
Work/Meetings
billing
personal

Gmail System Folders

Gmail has special system folders prefixed with [Gmail]/:

Folder	Description
`[Gmail]/All Mail`	Archive — all emails that aren't in Trash or Spam
`[Gmail]/Drafts`	Saved draft emails
`[Gmail]/Important`	Emails marked as important
`[Gmail]/Sent Mail`	Sent emails
`[Gmail]/Spam`	Spam folder
`[Gmail]/Starred`	Starred emails
`[Gmail]/Trash`	Deleted emails

Creating Folders

Create a new folder or label:

$ pontius folder create "Projects"
Folder created.
# Create nested folders with /
$ pontius folder create "Work/Projects/Alpha"
Folder created.

Deleting Folders

Remove a folder or label:

$ pontius folder delete "Old Projects"
Folder deleted.

Deleting Folders

Deleting a folder removes the label from all emails but doesn't delete the emails themselves. The emails will still exist in All Mail.

Moving Emails to Folders

Use the move command to label emails or move them to folders:

# Apply a label (Gmail)
$ pontius move 37801 "Work/Projects"
Moved.
# Move to system folder
$ pontius move 37801 "[Gmail]/Trash"
Moved.
# Move multiple emails
$ pontius move 37798,37799,37800 "billing"
Moved 3 emails.

Archiving vs Moving

There's a subtle difference between archiving and moving:

pontius archive — Removes email from INBOX but keeps it in All Mail. The email loses its INBOX label.
pontius move — Adds a label/moves to folder. For Gmail, this is adding a label, not necessarily removing from INBOX.

Gmail Behavior

In Gmail, moving an email to a label doesn't remove it from INBOX — the email will have both labels. To remove from INBOX while adding a label, archive first then move, or use the TUI to manage labels directly.

Listing Folder Contents

To see emails in a specific folder:

$ pontius list --folder "Work/Projects"
 UID    FROM                      SUBJECT
 37650  [email protected]            Project Alpha kickoff
 37645  [email protected]        New mockups ready
$ pontius list --folder "[Gmail]/Starred"
 UID    FROM                      SUBJECT
 37801  [email protected]      Contract review needed

Organization Tips

Keep it flat: While nested folders are supported, simpler structures are easier for AI to navigate.
Consistent naming: Use lowercase, no spaces for folder names that AI will reference frequently (e.g., billing not Billing Stuff).
Use archive: For emails you've processed, archive is usually better than moving to a "done" folder.