Gmail CLI: List Gmail Emails from Terminal

How do you use a Gmail CLI to read email from terminal?

Install the CLI, authenticate your Gmail account once, then run nylas email list, nylas email search, and nylas email read. That gives you a terminal Gmail workflow without creating a Google Cloud project or writing Gmail API client code.

If you are looking for a Gmail command line interface to access Gmail from command line scripts, the CLI keeps the commands provider-neutral while still authenticating through Google's OAuth flow behind the scenes.

Gmail is one of the most common mailboxes developers need to inspect from scripts, yet listing messages programmatically still starts with a Google Cloud project, an enabled Gmail API, OAuth consent configuration, and scoped access. That setup is useful for a full application, but it is heavy when you only need to read your own messages from a shell.

Google's Python quickstart for the Gmail API is 47 lines of code before you list a single message. The API returns message bodies as base64url-encoded MIME, so you also need to decode and parse them yourself. According to Google's Gmail API usage limits documentation, messages.list costs 5 quota units and messages.get costs another 20 — with a 2026 cap of 6,000 units per minute per user per project for new projects.

The gcloud CLI doesn't have email commands. Tools like fetchmail or offlineimap sync messages locally but don't give you a way to search or filter from the terminal.

1. Install the Nylas CLI

The Nylas CLI is a single binary that installs in under 30 seconds on macOS, Linux, and Windows. Homebrew is the fastest method for macOS and Linux — the formula pulls the latest release from GitHub and verifies SHA-256 checksums automatically.

brew install nylas/nylas-cli/nylas

The getting started guide covers all four install methods: Homebrew, shell script, PowerShell, and go install.

2. Connect your Gmail account

Authenticating the Nylas CLI with a Gmail account takes about 2 minutes. You create a Nylas application at dashboard-v3.nylas.com, connect your Gmail account through hosted OAuth, and copy the resulting API key. The CLI stores credentials locally in ~/.config/nylas/ so you only do this once.

Run nylas auth config to save your API key, then verify the connection with nylas auth whoami. The output confirms your email address and provider type.

nylas auth config
# Paste your API key when prompted

# Verify the connection
nylas auth whoami
# => Authenticated as you@gmail.com (Google)

3. List your emails

Listing Gmail messages with the Nylas CLI returns full message metadata — subject, sender, date, and read status — in a single request. Unlike the Gmail API, which returns only message IDs from messages.list and requires a second call per message to fetch content, the CLI returns complete message objects. The default output shows the 10 most recent messages sorted by date.

The --limit flag caps the number of results returned. The --unread flag filters to messages you haven't opened yet.

nylas email list              # recent emails
nylas email list --limit 10   # cap results
nylas email list --unread     # unread only

4. Search and filter

Searching Gmail from the command line uses the same query operators you'd type into Gmail's web search bar — from:, after:, before:, subject:, and has:attachment. The Nylas CLI passes these operators directly to Gmail's backend, so results match what you'd see in the browser. According to Google's search operator documentation, Gmail supports over 20 query operators for filtering messages.

The --limit flag controls how many matching results are returned. Combine multiple operators in a single quoted string to narrow results further.

nylas email search "invoice" --limit 5
nylas email search "from:boss@company.com"
nylas email search "after:2026-01-01 before:2026-02-01"

5. Read a specific email

Reading a specific Gmail message by ID returns the decoded body text directly in your terminal. The Gmail API requires a separate messages.get call that returns base64url-encoded MIME, costing 20 additional quota units per message according to Google's usage limits. The Nylas CLI decodes and renders the message body automatically.

Pass a message ID from a previous nylas email list result to nylas email read. The --mime flag outputs the raw MIME source instead of decoded text, which is useful for debugging email headers or encoding issues.

nylas email read msg_abc123          # decoded body
nylas email read msg_abc123 --mime   # raw MIME source

6. JSON output for scripting

Every Nylas CLI email command supports a --json flag that outputs structured JSON instead of human-readable text. This makes it straightforward to pipe results into jq, Python, or shell scripts for automation. Each JSON message object includes fields for id, subject, from, to, date, and unread status — typically 15-20 fields per message depending on the provider.

Combine --json with jq to extract specific fields. The first example counts unread messages; the second pulls subject lines from the five most recent emails.

nylas email list --unread --json | jq length
nylas email list --limit 5 --json | jq '.[].subject'

The script below prints a quick inbox summary — total unread count followed by the sender and subject of the five most recent unread messages.

#!/bin/bash
unread=$(nylas email list --unread --json | jq length)
echo "Unread emails: $unread"

nylas email list --unread --json \
  | jq -r '.[] | "\(.from[0].email): \(.subject)"' \
  | head -5

7. Work with Gmail labels

Gmail organizes messages with labels rather than traditional IMAP folders. A single Gmail message can carry multiple labels simultaneously — for example, both "INBOX" and "IMPORTANT" — which differs from folder-based providers like Outlook where a message lives in exactly one folder. The Nylas CLI maps Gmail labels to a unified folder model, letting you filter by label name with the --folder flag.

Gmail includes 13 built-in system labels (INBOX, SENT, DRAFT, SPAM, TRASH, STARRED, IMPORTANT, UNREAD, and five CATEGORY_* labels). Run nylas email folders list to see all available labels, including custom ones you've created.

# List emails in a specific label
nylas email list --folder "INBOX"
nylas email list --folder "IMPORTANT"
nylas email list --folder "STARRED"

# List all available labels/folders
nylas email folders list

# Filter promotions and social
nylas email list --folder "CATEGORY_PROMOTIONS" --limit 5
nylas email list --folder "CATEGORY_SOCIAL" --limit 5

8. Gmail API vs Nylas CLI

The Gmail API Python quickstart requires 47 lines of code and 5 distinct setup steps — creating a GCP project, enabling the API, configuring an OAuth consent screen, downloading credentials, and writing the client code — before you can list a single message. The Nylas CLI reduces that to 2 commands: nylas auth config and nylas email list. The table below compares each step side by side.

9. Google Workspace accounts

Google Workspace has over 3 billion users across 10 million paying organizations, according to Google's 2024 Cloud Next keynote. The Nylas CLI works with both personal Gmail accounts and Google Workspace accounts using the same authentication flow. Workspace users authenticate with their own credentials through standard OAuth2 — no domain-wide delegation or service account setup is needed.

• Domain-wide delegation is not required — users authenticate with their own credentials
• Admin consent may be required if your Workspace admin restricts third-party app access
• Service accounts are not needed — the CLI uses standard OAuth2 user consent

If your Workspace admin has restricted third-party access, ask them to allow the Nylas application in the Google Admin console under Security → API controls → App access control.

Next steps

• Send email from the terminal — send, schedule, and track emails
• Send Gmail from command line — send Gmail messages from terminal without Gmail API client code
• Email CLI tools compared — compare Gmail CLI workflows with mailx, mutt, msmtp, and swaks
• AI agent CLI for email and calendar — wrap Gmail commands as JSON tools for LLM agents
• List Outlook emails — same workflow for Microsoft 365
• List Yahoo Mail emails — same workflow for Yahoo
• List iCloud Mail emails — same workflow for Apple
• List IMAP emails — works with Fastmail, Zoho, and more
• List Exchange emails — same workflow for Exchange
• Gmail API pagination and sync explained — nextPageToken, historyId, and how to skip both
• Gmail API search query examples — q, labels, categories, date filters, attachments, and rfc822msgid
• Gmail API quotas in 2026 — current method costs, rate limits, and safer agent patterns
• Give AI agents email access via MCP — connect Claude, Cursor, or VS Code to your inbox
• Getting started with Nylas CLI — install, setup wizard, and first-run walkthrough
• Move emails between folders — create Gmail labels, list folder contents, and organize messages
• Full command reference — every flag and subcommand documented
• Gmail API: Searching for messages — canonical query operators (from:, subject:, has:, before:, after:) the CLI exposes