DEV Community

Qasim Muhammad
Qasim Muhammad

Posted on

The CLI-First Way to Manage Agent Accounts

#cli #email #devops #productivity

There's a specific kind of friction in provisioning infrastructure through a web UI: you're building an automated system, but step one is clicking through a dashboard. For email identities that your code creates, monitors, and tears down, the browser is the wrong tool. The Nylas CLI closes that gap — every part of an Agent Account's lifecycle is a terminal command.

Agent Accounts (currently in beta) are hosted mailboxes with real addresses that your application owns end-to-end. They send, receive, and hold calendar events like any human account, and the quickstart gets you from API key to working mailbox in under 5 minutes. Here's how to do all of it without leaving the shell.

One-time setup

If you've never touched the CLI before:

brew install nylas/nylas-cli/nylas
# or, without Homebrew:
curl -fsSL https://cli.nylas.com/install.sh | bash

nylas init
Enter fullscreen mode Exit fullscreen mode

nylas init opens a browser once for account creation and sign-in — the only step that needs a human. After that, verify with nylas auth whoami --json, which returns your active grant, provider, and status as parseable JSON. If you already have an API key, skip the browser entirely with nylas init --api-key <NYLAS_API_KEY> (add --region eu for EU data residency).

Want to confirm the binary works before wiring up credentials? nylas demo email list returns sample data with no authentication at all — useful in provisioning scripts that should fail fast if the install step broke.

Creating accounts

With a domain registered (either your own with MX and TXT records, or a *.nylas.email trial subdomain for instant testing), creation is one line:

nylas agent account create agent@yourdomain.com
Enter fullscreen mode Exit fullscreen mode

The CLI prints the new grant ID plus status and connector details. That grant ID is the handle for everything else — messages, calendar, webhooks.

Want a human to supervise the mailbox from Outlook or Apple Mail? Create it with IMAP/SMTP access enabled:

nylas agent account create agent@yourdomain.com --app-password "MySecureP4ssword!2024"
Enter fullscreen mode Exit fullscreen mode

Discovery and health checks

Three commands cover the "what do I have and is it working" questions:

nylas agent account list --json     # every Agent Account on the application
nylas agent account get agent@yourdomain.com   # one account, by ID or email
nylas agent status --json           # connector readiness
Enter fullscreen mode Exit fullscreen mode

Accounts also show up in nylas auth list with Provider: Nylas, side by side with any OAuth-connected grants. Switch between them with nylas auth switch, and the regular email and calendar commands operate on whichever is active:

nylas email list --limit 5 --json
nylas email send --to "you@example.com" --subject "Hi" --body "From the agent." --yes
nylas calendar events list --days 7 --json
Enter fullscreen mode Exit fullscreen mode

Note the flags. The autonomous agents guide is blunt about this: always pass --json for parseable output, always pass --yes on sends and deletes so nothing blocks on a confirmation prompt, and always pass --limit (start with 5) so list commands don't flood whatever's consuming the output.

Daily driving the mailbox

Once an account exists, the everyday email commands go well beyond list-and-send. Search, read a specific message, and even schedule delivery for later:

nylas email search "meeting agenda" --limit 5 --json
nylas email read <MESSAGE_ID> --json

nylas email send \
  --to "alice@example.com" \
  --cc "bob@example.com" \
  --subject "Project update" \
  --body "Status report attached." \
  --schedule "tomorrow 9am" \
  --yes
Enter fullscreen mode Exit fullscreen mode

The calendar side has a similar range — list events, create them with explicit timestamps, or find a slot that works for multiple people:

nylas calendar find-time \
  --participants "alice@example.com,bob@example.com" \
  --duration 30m \
  --json

nylas calendar schedule ai "Find 30 minutes with Alice next week"
Enter fullscreen mode Exit fullscreen mode

That last one is natural-language scheduling: you hand it a sentence, it works out the slot. All of these operate on whichever grant is active, so they work identically against an Agent Account and a human's OAuth-connected mailbox.

Governance from the terminal

Policies and rules — the guardrails that control send limits, spam handling, and inbound filtering — are inspectable the same way:

nylas agent policy list
nylas agent rule list
Enter fullscreen mode Exit fullscreen mode

And webhooks, so your code reacts to inbound mail in real time:

nylas webhook triggers     # see what you can subscribe to
nylas webhook create \
  --url https://youragent.example.com/webhooks/nylas \
  --triggers "message.created,message.updated"
nylas webhook list
Enter fullscreen mode Exit fullscreen mode

These work against any grant, connected or agent-owned.

Teardown

Ephemeral identities only make sense if destruction is as cheap as creation:

nylas agent account delete agent@yourdomain.com --yes
Enter fullscreen mode Exit fullscreen mode

Delete by email or by grant ID; --yes skips the confirmation so it's scriptable.

When something breaks

The failure modes are predictable enough to script around. The autonomous agents guide ships a troubleshooting table; here's the short version:

Symptom Fix
nylas: command not found Re-run the install, or use the full path (/opt/homebrew/bin/nylas)
error.type: "unauthorized" Run nylas dashboard apps apikeys create to mint a new API key
not_found_error on a grant Run nylas auth login to reconnect
rate_limit_error Back off and retry
Commands hang You forgot --yes on a send or delete
Empty results nylas auth list to check accounts, nylas auth switch to change

Errors come back in the same JSON envelope as the API — a request_id plus an error object with type and message — so a script can branch on error.type instead of grepping prose.

Where this beats the dashboard

The dashboard is fine for a first look. The CLI wins everywhere else:

  • CI and scripts. Provision a mailbox in a pipeline, run a test against it, delete it. No API client code, no session cookies.
  • Repeatability. A create command in a setup script is documentation; a sequence of dashboard clicks isn't.
  • Agent-friendliness. An AI agent can run these commands itself. The structured --json output and non-interactive --yes flag exist precisely so an autonomous process never hangs on a prompt.
  • Credential extraction. nylas auth token prints the raw API key and nylas auth whoami --json gives you the grant ID — two commands and your .env is populated.

There's also an escape hatch in both directions. Everything the CLI does maps to plain API calls (account creation is POST /v3/connect/custom with "provider": "nylas"), so you can graduate to SDK code whenever a script outgrows the shell. And if your editor or agent speaks MCP, nylas mcp install registers 16 email, calendar, and contacts tools so you skip subprocess calls entirely.

Next step: register a trial domain, run nylas agent account create test@your-application.nylas.email, and send yourself a message from it. Total elapsed time should be a coffee refill. Then check nylas agent status --json and see what a healthy connector looks like before you build anything on top.

Top comments (0)