Guide

List Your Gmail Emails from the Command Line

The Gmail API requires OAuth client setup, service account configuration, and Python or Node client libraries just to list your own inbox. The Nylas CLI handles OAuth2 and provider abstraction behind the scenes — authenticate once, then list, search, and read emails with a single command.

The problem with the Gmail API

To list emails programmatically with Google, you need to create a Cloud project, enable the Gmail API, configure OAuth consent, download credentials, and write code using the Google client library. That is a lot of ceremony to read your own inbox.

The gcloud CLI does not have email commands. Tools like fetchmail or offlineimap sync messages locally but do not give you a clean way to search or filter from the command line.

1. Install the Nylas CLI

# macOS / Linux (Homebrew)
brew install nylas/nylas-cli/nylas

# Or build from source (requires Go 1.23+)
go install github.com/nylas/cli/cmd/nylas@latest

2. Connect your Gmail account

Head to dashboard-v3.nylas.com, create an application, and connect your Gmail account. Then grab your API key:

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

# List recent emails
nylas email list

# Limit results
nylas email list --limit 10

# Only unread emails
nylas email list --unread
# Search by keyword
nylas email search "invoice" --limit 5

# Search by sender
nylas email search "from:boss@company.com"

# Search within a date range
nylas email search "after:2026-01-01 before:2026-02-01"

5. Read a specific email

# Read an email by ID (IDs are shown in list output)
nylas email read msg_abc123

# Read the raw MIME source
nylas email read msg_abc123 --mime

6. JSON output for scripting

Every command supports --json output, so you can pipe it into jq, a script, or an AI agent:

# Count unread emails
nylas email list --unread --json | jq length

# Extract subjects
nylas email list --limit 5 --json | jq '.[].subject'

A quick script to summarize your inbox:

#!/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 uses labels instead of traditional folders. The Nylas CLI maps Gmail labels to folders, so you can filter by label:

# 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 folder 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

Here is what it takes to list emails with each approach:

StepGmail APINylas CLI
Create projectGoogle Cloud ConsoleNot required
Enable APIEnable Gmail API in consoleNot required
OAuth setupConfigure consent screen, scopes, redirect URIsHandled by Nylas dashboard
CredentialsDownload JSON, manage refresh tokensnylas auth config
CodePython/Node client library, ~30 lines minimumZero code
List emailsservice.users().messages().list()nylas email list
PaginationHandle nextPageToken manually--limit flag
Read email bodySeparate messages().get() call, decode base64nylas email read

9. Google Workspace accounts

The Nylas CLI works with both personal Gmail accounts and Google Workspace (formerly G Suite) accounts. For Workspace accounts:

  • 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