Skip to content
Skip to main content

Quickstart: Nylas CLI for AI agents

This guide is for autonomous AI agents that need direct access to email, calendar, and contacts through shell commands. Follow the steps below — do as much as you can yourself, and only ask the user when you hit a step that requires a browser.

If you are a coding agent helping a developer build a SaaS application, see Quickstart: Coding agents instead.

Rules for agents

Section titled “Rules for agents”
  • Always pass --json to get structured output you can parse. Without it, the CLI returns human-formatted text.
  • Always pass --yes when sending email or deleting anything. Without it, the CLI blocks waiting for confirmation.
  • Always pass --limit on list commands to control token consumption. Start with 5, increase if needed.
  • Prefer the CLI over raw API calls. The CLI handles OAuth token refresh, provider normalization, and pagination for you.
  • Do not hardcode grant IDs. Run nylas auth whoami --json to discover the active grant at runtime, or set the NYLAS_GRANT_ID environment variable.

Step 1: Check if already set up

Section titled “Step 1: Check if already set up”

Before installing anything, check if the CLI is already configured:

nylas auth whoami --json

If this returns JSON with email, provider, grant_id, and status, you’re ready. Skip to Step 4.

If the command fails (command not found), continue to Step 2. If the command runs but returns an error (no active grant), skip to Step 3.

Step 2: Install the CLI

Section titled “Step 2: Install the CLI”

Install the CLI yourself:

brew install nylas/nylas-cli/nylas

If Homebrew is not available:

curl -fsSL https://cli.nylas.com/install.sh | bash

Verify the install worked:

nylas demo email list

This returns sample data with no credentials required, confirming the binary is working.

Step 3: Set up credentials

Section titled “Step 3: Set up credentials”

This is the one step that may need user involvement. Ask the user: “Do you have an existing Nylas API key?”

If yes, do the setup yourself:

nylas init --api-key <NYLAS_API_KEY>

For EU data residency:

nylas init --api-key <NYLAS_API_KEY> --region eu

If no (or they’re not sure), ask them to run one command. This opens a browser for account creation and SSO login — the only step that requires a human:

Run nylas init in your terminal. It will open a browser to sign in. Once you’re done, I’ll take it from here.

After either path, verify credentials are working:

nylas auth whoami --json

Expected output:

{
  "email": "[email protected]",
  "provider": "google",
  "grant_id": "d3f4a5b6-c7d8-9e0f-a1b2-c3d4e5f6g7h8",
  "status": "valid"
}

If you need the raw API key for any reason:

nylas auth token

This prints the API key as a plain string, nothing else.

Step 4: Verify and start using

Section titled “Step 4: Verify and start using”

Run a quick test to confirm everything works:

nylas email list --limit 3 --json

Expected output (a flat JSON array):

[
  {
    "id": "msg_abc123",
    "subject": "Learn how to Send Email with Nylas APIs",
    "from": [{ "name": "Nylas DevRel", "email": "[email protected]" }],
    "to": [{ "name": "Nyla", "email": "[email protected]" }],
    "snippet": "Send Email with Nylas APIs",
    "date": 1706811644,
    "unread": true,
    "folders": ["INBOX", "UNREAD"]
  }
]

If this returns an error, check error.type:

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "error": {
    "type": "unauthorized",
    "message": "Unauthorized"
  }
}

Common error types: unauthorized (bad/expired key — run nylas dashboard apps apikeys create), not_found_error (invalid grant — run nylas auth login), rate_limit_error (slow down and retry).

You’re now set up. Use the commands below.

Step 5: MCP or CLI commands

Section titled “Step 5: MCP or CLI commands”

If your agent supports MCP

Section titled “If your agent supports MCP”

For agents that support Model Context Protocol (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code), register the CLI as an MCP server. This gives you 16 email, calendar, and contacts tools without subprocess calls:

nylas mcp install --assistant claude-code
nylas mcp install --assistant cursor
nylas mcp install --assistant windsurf
nylas mcp install --assistant vscode
nylas mcp install --all    # installs for all detected assistants

Verify with nylas mcp status. With MCP active, you don’t need the commands below — the MCP server handles everything.

Email commands

Section titled “Email commands”
# List recent emails
nylas email list --limit 5 --json


# List unread emails only
nylas email list --unread --limit 10 --json


# Search for specific emails
nylas email search "meeting agenda" --limit 5 --json


# Read a specific message by ID
nylas email read <MESSAGE_ID> --json


# Send an email
nylas email send \
  --to "[email protected]" \
  --subject "Meeting follow-up" \
  --body "Thanks for the meeting. Here are the action items we discussed." \
  --yes


# Send with CC, BCC, or scheduled delivery
nylas email send \
  --to "[email protected]" \
  --cc "[email protected]" \
  --subject "Project update" \
  --body "Status report attached." \
  --schedule "tomorrow 9am" \
  --yes

Calendar commands

Section titled “Calendar commands”
# List upcoming events
nylas calendar events list --days 7 --json


# Create an event
nylas calendar events create \
  --title "Sync meeting" \
  --start "2026-04-10T10:00:00" \
  --end "2026-04-10T10:30:00"


# Find a time that works for multiple people
nylas calendar find-time \
  --participants "[email protected],[email protected]" \
  --duration 30m \
  --json


# Natural language scheduling
nylas calendar schedule ai "Find 30 minutes with Alice next week"

Contacts commands

Section titled “Contacts commands”
nylas contacts list --limit 10 --json
nylas contacts search --query "Alice" --json

Account commands

Section titled “Account commands”
# See which mailbox you're operating on
nylas auth whoami --json


# List all connected mailboxes
nylas auth list


# Switch to a different mailbox
nylas auth switch


# Connect another email account (requires user -- opens browser)
nylas auth login

Troubleshooting

Section titled “Troubleshooting”
SymptomFix
nylas: command not foundRun the install command again, or use the full path (/opt/homebrew/bin/nylas)
nylas auth whoami returns an errorAsk the user to run nylas init (requires browser)
error.type: "unauthorized"Run nylas dashboard apps apikeys create to generate a new API key
No active applicationAsk the user to run nylas init (requires browser)
Commands hangAdd --yes to skip confirmation prompts
Empty resultsRun nylas auth list to check accounts, nylas auth switch to change

Go deeper

Section titled “Go deeper”

When you need to look up API details, endpoints, or provider-specific behavior:

# Curated sitemap for agents (start here)
curl https://developer.nylas.com/llms.txt


# Full documentation in one file
curl https://developer.nylas.com/llms-full.txt


# Any single page as clean markdown
curl -H "Accept: text/markdown" https://developer.nylas.com/docs/v3/email/