mvanhorn Nylas — Printing Press CLI
Prerequisites: Install the CLI
This skill drives the nylas-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
- Install via the Printing Press installer. It defaults binaries to
$HOME/.local/binon macOS/Linux and%LOCALAPPDATA%\Programs\PrintingPress\binon Windows:npx -y @mvanhorn/printing-press-library install nylas --cli-only - Verify:
nylas-pp-cli --version - Ensure the reported install directory is on
$PATHfor the agent/runtime that will invoke this skill.
If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):
go install github.com/mvanhorn/printing-press-library/library/productivity/nylas/cmd/nylas-pp-cli@latest
If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.
When to Use This CLI
Reach for nylas-pp-cli when you need to query Nylas data across multiple grants, run repeat 'what changed since' polls cheaply, compose SQL over messages and events, or sample the wire payload of a send before it goes out. For pure single-call API parity with the official SDK, the official nylas-cli is also a fine choice.
Unique Capabilities
These capabilities aren't available in any other tool for this API.
Local state that compounds
sync— Pull messages, events, threads, and contacts for one or all grants into a local SQLite mirror with per-(grant, resource) cursors so re-runs are incremental.Reach for this when an agent needs to answer questions repeatedly without burning rate-limit on every call.
nylas-pp-cli sync --resources messages,events --since 24h --agentsince— Query the local mirror for resources changed in the last N (e.g. 2h, 24h) across all grants in one shot.Cheapest path to 'what changed' polling without API round-trips.
nylas-pp-cli since 2h --resource messages --agent --select id,subject,from,grant_idsearch— FTS5 search over messages, threads, events, and contacts spanning every connected grant in a single query (use --type to filter by resource).Use this to find references anywhere across a tenant without N separate searches.
nylas-pp-cli search "invoice overdue" --type messages --limit 50 --agentexport— Stream the local mirror (or a filtered slice) to NDJSON for downstream analytics tools like DuckDB or notebooks.Pipe Nylas data into duckdb or a notebook in one command.
nylas-pp-cli export --resource messages --since 90d --format ndjson
Cross-grant analytics
gravity— Rank contacts by cross-grant interaction weight (sent + received + meeting-attended), unified by email address.Surfaces 'who actually matters to this tenant' in one call for CRM hygiene or agent prioritisation.
nylas-pp-cli gravity --top 25 --since 90d --agentresponse-time— Compute median and p90 first-response latency on threads where the grant-holder replied, sliced by grant or counterparty domain.An SLA dashboard in one command, impossible against the live API in under five minutes of round-trips.
nylas-pp-cli response-time --group-by domain --since 30d --agent
Reliability & safety
webhook-replay— Re-fire any past webhook delivery from the local store into a local handler URL, optionally filtered by trigger or grant.Reproduce a production webhook bug in seconds without waiting for the next event to fire.
nylas-pp-cli webhook-replay --since 24h --trigger message.created --to http://localhost:3000/hookgrants messages send— Use --dry-run to print the exact wire payload for any grants messages send call; pair with --yes (or --agent) to bypass interactive confirmation only when you've reviewed the preview.Every destructive action is reviewable; an agent can show the payload before sending.
nylas-pp-cli grants messages send 550e8400-e29b-41d4-a716-446655440000 --to PII_EMAIL_EXAMPLE --body 'note' --dry-run
nylas-pp-cli grants messages send 550e8400-e29b-41d4-a716-446655440000 --to PII_EMAIL_EXAMPLE --body 'note' --yes
- **`grants messages send`** — Pass the global --idempotent flag so an already-existing create result is treated as a successful no-op, making the send safe to retry inside an agent loop.
_Safe to call inside an agent retry loop._
```bash
nylas-pp-cli grants messages send 550e8400-e29b-41d4-a716-446655440000 --to PII_EMAIL_EXAMPLE --body 'note' --idempotent --agent
grants doctor— Health-check every grant: token expiry, missing scopes for advertised features, recent webhook failures, sync lag.Tells you which mailboxes are quietly broken before users notice.
nylas-pp-cli grants doctor --agent
Agent-native plumbing
sql— Read-only SQL query against the local mirror with --json output.Anything we forgot to expose as a verb, an LLM can still answer through SQL.
nylas-pp-cli sql "SELECT from_addr, COUNT(*) FROM messages GROUP BY 1 ORDER BY 2 DESC LIMIT 20" --agent--agent (global flag)— Single flag that forces --json --compact --no-input --no-color --yes defaults so any read command is LLM-safe in one switch.One flag flips the entire CLI into LLM-safe mode; eliminates a class of prompt-eats-stdin bugs.
nylas-pp-cli grants get-all --agent --limit 10
Command Reference
admin — Manage admin
nylas-pp-cli admin create-api-key— ⚠️ Before you can use the Manage API Keys endpoints, you need to <a...nylas-pp-cli admin create-domain— ⚠️ Before you can use the Manage Domains endpoints, you need a <a...nylas-pp-cli admin delete-api-key— ⚠️ Before you can use the Manage API Keys endpoints, you need to <a...nylas-pp-cli admin delete-domain— ⚠️ Before you can use the Manage Domains endpoints, you need a <a...nylas-pp-cli admin get-api-key— ⚠️ Before you can use the Manage API Keys endpoints, you need to <a...nylas-pp-cli admin get-api-keys— ⚠️ Before you can use the Manage API Keys endpoints, you need to <a...nylas-pp-cli admin get-domain— ⚠️ Before you can use the Manage Domains endpoints, you need a <a...nylas-pp-cli admin get-domain-info— ⚠️ Before you can use the Manage Domains endpoints, you need a <a...nylas-pp-cli admin list-domains— ⚠️ Before you can use the Manage Domains endpoints, you need a <a...nylas-pp-cli admin update-domain— ⚠️ Before you can use the Manage Domains endpoints, you need a <a...nylas-pp-cli admin verify-domain— ⚠️ Before you can use the Manage Domains endpoints, you need a <a...
applications — In the context of the Nylas APIs, an "application" is the object record of your Nylas application.
The Nylas application is the central resource for your Nylas implementation. It collects the connectors that you use to store information about third party services that your application connects to, and stores the grants that you create when using connectors.
Nylas applications also allow you to define your specific branding, change the look and feel of the Nylas Hosted authentication flow, and list your application's callback URIs.
Application callback URIs
Your Nylas application includes a list of allowed callback URIs. These are known URIs that Nylas can direct users to after authentication. You need to define at least one callback URI so your users can complete the auth flow.
You must include any callback URIs you plan to use in this list. If an auth payload includes a callback URI that isn't on the list, the whole authentication flow fails.
Application limitations
Keep the following limitations in mind as you work with Nylas applications:
Applications are the central resource that stores other Nylas resources. You must create an application before you can create any other parts of your Nylas implementation.
Applications can be associated with only one project at a time. While your project can have more than one Nylas application to provide different authentication experiences, you cannot share applications, connectors, or grants between more than one project.
Applications cannot be nested, and cannot be set up with parent-child relationships.
Your application must have at least one callback URI, or else it cannot finish the authentication flow, which means it cannot create grants. Nylas requires grants to access user data.
- In an ideal scenario, your application will have multiple callback URIs defined.
nylas-pp-cli applications add-callback-uri— Adds a callback URI to the specified Nylas application. Nylas uses callback URIs to redirect users to your project...nylas-pp-cli applications delete-callback-uri— Deletes the specified callback URI.nylas-pp-cli applications get— Gets the application objectnylas-pp-cli applications get-all-callback-uris— Returns a list of callback URIs for the specified Nylas application.nylas-pp-cli applications get-callback-uri— Returns the specified callback URI.nylas-pp-cli applications update— Updates a Nylas application using the client ID associated with the specified API key. <div...nylas-pp-cli applications update-callback-uri— Updates the specified callback URI. If you don't define theplatform, Nylas doesn't modify the existing settings....
calendars — The Nylas Calendar API allows you to create and manage calendars, and access the events they contain. Nylas uses the same commands to manage calendars across providers, and you can refer to specific calendars using the provider's calendar_id.
Depending on the provider, a calendar might be accessed by only one person, or shared among several users. Some common calendars might include Personal, Work, or Shared calendars.
A calendar might contain overlapping events or conflicting schedules. You can use the Get Availability endpoint to find the best time for an event by identifying time periods that have no conflicting events among all participants.
Find a calendar ID
You must specify a calendar_id in all calls you make to the Nylas Calendar API. You can use primary to specify the primary calendar associated with a grant, or you can look up the ID of the calendar that you want to work with and use that.
For virtual calendars, the primary calendar is the first created for a virtual account. You cannot delete a virtual calendar that's designated as primary.
For iCloud, there is no primary calendar.
Free/Busy information
The Get Free/Busy Schedule endpoint is available for all providers, including Virtual Calendars, except for iCloud.
The Get Availability endpoint doesn't support the free_busy object.
Virtual calendars
Nylas allows you to create virtual calendars for users and resources that might not have calendars on your providers (for example, external contractors or meeting rooms). You can use the Nylas Calendar and Events APIs with the virtual accounts that power virtual calendars, just like you would any other account. Virtual accounts don't provide email or contacts features, so you can't use them with the Email or Contacts APIs.
For more information, see Using virtual calendars.
Metadata on calendars
You can add metadata to new and existing calendars by including the metadata sub-object in your POST, PUT, or PATCH request. For more information, see the Metadata documentation.
Calendar scopes
The table below lists the Calendar endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopeshttps://www.googleapis.com/auth/... |
Microsoft Scopeshttps://graph.microsoft.com/... |
|---|---|---|
GET /calendarsGET /calendars/<CALENDAR_ID>POST /calendars/free-busyPOST /calendars/availability |
/calendar.readonly ☑️/calendar |
Calendars.Read ☑️Calendars.ReadWrite |
POST /calendarsPUT /calendars/<CALENDAR_ID>DELETE /calendars/<CALENDAR_ID> |
/calendar ☑️ |
Calendars.ReadWrite ☑️ |
For more information about scopes, see Using scopes to request user data.
Calendar activity notifications
You can subscribe to the following triggers so Nylas notifies you about changes to your users' calendar data:
calendar.createdcalendar.updatedcalendar.deleted
For more information, see the Calendar webhook notification schemas.
Microsoft event considerations
Microsoft Outlook events are often shared across all calendars in a user's account. If the user creates an event on one of their calendars, you can retrieve it using another calendar ID from their grant.
nylas-pp-cli calendars— Returns availability information for the specified user or group of users. All participants' email addresses must be...
channels — Manage channels
nylas-pp-cli channels create-pubsub— Create a Pub/Sub channel in the specified application.nylas-pp-cli channels create-sns— Create an Amazon SNS notification channel in the specified application. Thetopicmust be a valid Amazon SNS topic...nylas-pp-cli channels delete-pubsub-by-id— Delete a specific Pub/Sub channel from a specific Nylas application.nylas-pp-cli channels delete-sns-by-id— Delete a specific Amazon SNS notification channel from a specific Nylas application.nylas-pp-cli channels get-pubsub— Get the Pub/Sub channels for an application.nylas-pp-cli channels get-pubsub-by-id— Get a specific Pub/Sub channel from a specific Nylas application.nylas-pp-cli channels get-sns— Get the Amazon SNS notification channels for an application.nylas-pp-cli channels get-sns-by-id— Get a specific Amazon SNS notification channel from a specific Nylas application.nylas-pp-cli channels put-pubsub-by-id— Updates the specified Pub/Sub channel. When you make aPUTrequest, Nylas replaces all data in the nested object...nylas-pp-cli channels put-sns-by-id— Updates the specified Amazon SNS notification channel. When you make aPUTrequest, Nylas replaces all data in the...
connect — Manage connect
nylas-pp-cli connect byo-auth— Manually creates a grant using the Bring Your Own (BYO) Authentication flow. If you're handling the OAuth flow in...nylas-pp-cli connect exchange-oauth2-token— The standard OAuth token endpoint for Hosted Authentication. This endpoint doesn't require authentication, as it is...nylas-pp-cli connect get-oauth2-flow— The initial OAuth 2.0 authorization request. Use this endpoint with the required query parameters to start the OAuth...nylas-pp-cli connect info-oauth2-token— Get info about a specific token based on the identifier you include. Use either the ID Token or Access...nylas-pp-cli connect revoke-oauth2-token-and-grant— Revokes the specified OAuth access token. When you revoke the token, Nylas doesn't revoke the grant or the...
connectors — Manage connectors
nylas-pp-cli connectors create— Create a connector in your Nylas application. Connectors are how your Nylas application stores information it needs...nylas-pp-cli connectors delete-by-provider— Delete the existing connector for the provider you specify.nylas-pp-cli connectors get-all— List the connectors in your Nylas application.nylas-pp-cli connectors get-by-provider— Returns a connector for the specified provider.nylas-pp-cli connectors update-by-provider— Update the connector for the specified provider. When you make aPATCHrequest, Nylas replaces all data in the...
domains — Manage domains
grants — Manage grants
nylas-pp-cli grants delete-by-id— Delete an existing grant by ID. You cannot re-authenticate the deleted grant. If you try to re-authenticate it,...nylas-pp-cli grants get-all— Returns all grants in your Nylas application.nylas-pp-cli grants get-by-access-token— Gets a grant using current access tokennylas-pp-cli grants get-by-id— Gets a grant with the provided ID. If the grant'sgrant_statusisinvalid, the grant has expired and needs to be...nylas-pp-cli grants patch-by-id— Updates the specified grant's stored settings or scope metadata. Common use cases: - Rotate a refresh token...
lists — The Lists endpoints let you manage typed collections of values (email addresses, domains, or top-level domains) that can be referenced by Rules using the in_list condition operator. Lists provide a way to maintain dynamic allow lists and block lists that are evaluated during inbound rule processing and outbound send evaluation without needing to update individual rules.
Each list has a type that determines what kind of values it accepts and which rule condition fields it can be matched against:
domain— Domain names (for example,example.com). Matched against thefrom.domainorrecipient.domainrule condition.tld— Top-level domains (for example,com,xyz). Matched against thefrom.tldorrecipient.tldrule condition.address— Full email addresses (for example,PII_EMAIL_EXAMPLE). Matched against thefrom.addressorrecipient.addressrule condition.
List type is set at creation time and cannot be changed. Items within a list are managed via the /v3/lists/{list_id}/items sub-resource endpoints. Values are automatically normalized (lowercased and trimmed) and validated against the list's type. Duplicate additions are silently ignored.
nylas-pp-cli lists create— Creates a list for your application. Lists are typed collections of values (domains, TLDs, or email addresses) that...nylas-pp-cli lists delete— Deletes the specified list. This action is irreversible and cascades to all items in the list. Rules that reference...nylas-pp-cli lists get— Returns the specified list.nylas-pp-cli lists list-lists— Returns all lists for your application.nylas-pp-cli lists update— Updates the specified list. Onlynameanddescriptioncan be updated. The listtypeis immutable after creation.
migration-tools — Manage migration tools
nylas-pp-cli migration-tools migration-clone-single-account— Migrates a single v2 connected account to a v3 grant. Use this endpoint to migrate a few accounts to v3 as a test,...nylas-pp-cli migration-tools migration-get-jobs— Get information about the migration jobs for your application, including progress and status, for currently running...nylas-pp-cli migration-tools migration-import-v2-app— Import the settings from a v2 Nylas application to its linked v3 application. Before you use this endpoint, make...nylas-pp-cli migration-tools migration-link-v2v3-apps— Link an existing v2 application to an existing v3 application. ⚠️Your v2...nylas-pp-cli migration-tools migration-snapshot-batch-clone— Starts a batch migration job to clone v2 connected accounts to v3 grants. Before you use this endpoint, your v2...nylas-pp-cli migration-tools translate-v2id-to-provider-id— Use the connected account ID and a resource type, with an optional list of specific Nylas IDs, to get a response...
notetakers — Nylas Notetaker is a real-time meeting bot that you can invite to your online meetings. It records and transcribes your discussion, and delivers results to you using the Nylas API and webhook notifications.
The /v3/grants/<NYLAS_GRANT_ID>/notetakers endpoints let you interact with Nylas Notetaker while referencing a specific grant so you can use Notetaker's calendar sync features for your authenticated users.
The /v3/notetakers endpoints let you send Notetakers that aren't connected to a grant as standalone Notetakers.
Calendar sync
Notetaker works with the Nylas Calendar API to automatically sync with calendars and events. When you sync Notetaker with a grant's calendar or event, Nylas tracks their join times and meeting links so the Notetaker is always sent to the meeting on time.
Webhook notifications
Nylas sends webhook notifications when a Notetaker bot is created, updated, or deleted, and when the recording media is available.
nylas-pp-cli notetakers delete-standalone— Permanently deletes the specified Notetaker and all associated data, including any recordings, transcripts,...nylas-pp-cli notetakers get-all-standalone— Returns a list of standalone Notetaker bots.nylas-pp-cli notetakers get-standalone— Returns the specified Notetaker bot and its details.nylas-pp-cli notetakers invite-standalone— Adds a standalone Notetaker bot to the specified meeting. ℹ️ Nylas doesn't...nylas-pp-cli notetakers update-standalone— Updates the specified scheduled standalone Notetaker bot.
policies — The Policies endpoints let you define the operational configuration for Nylas Agent Accounts, including message limits, attachment constraints, spam detection settings, and linked rules for inbound message filtering. Each policy is scoped to your application and can be assigned to one or more Agent Accounts.
Policies let you control:
- Limits — Attachment sizes, counts, allowed types, total storage, daily message quotas, and retention periods for the inbox and spam folders.
- Spam detection — DNS-based block list (DNSBL) checking, header anomaly detection, and sensitivity tuning.
- Options — Additional folder creation and CIDR-based email aliasing.
- Rules — Link filtering rules (created via the Rules API) to automatically process inbound messages based on sender criteria.
Policy limits are validated against your plan's maximum values. If a limit field is omitted, it defaults to the plan maximum. If a requested value exceeds the plan limit, the API returns an error.
nylas-pp-cli policies create-policy— Creates a policy for your application. Policies define message limits, spam detection settings, options, and linked...nylas-pp-cli policies delete-policy— Deletes the specified policy. This action is irreversible.nylas-pp-cli policies get-policy— Returns the specified policy.nylas-pp-cli policies list— Returns a list of all policies for your application.nylas-pp-cli policies update-policy— Updates the specified policy. All fields are optional — only provided fields are updated. The same plan-limit,...
providers — Manage providers
nylas-pp-cli providers— Returns the provider if one is detected. This operation is rate limited to 20 calls per minute for each Nylas...
rules — The Rules endpoints let you define automated filtering and routing logic for Nylas Agent Accounts. Each rule specifies a trigger (inbound or outbound), matching conditions, and actions to perform when those conditions are met.
Inbound rules run when mail arrives. Conditions match the sender — from.address, from.domain, or from.tld. Actions include blocking the message at the SMTP level, marking as spam, assigning to a folder, marking as read or starred, archiving, and trashing.
Outbound rules run before a send is submitted to the email provider. Conditions can match sender data (from.address, from.domain, from.tld), recipient data (recipient.address, recipient.domain, recipient.tld), or the send type via outbound.type (compose for new messages, reply for replies). A block action on an outbound rule rejects the send with HTTP 403 before it reaches the provider, so no message is delivered and no sent copy is stored. Non-blocking actions (mark_as_spam, archive, mark_as_read, mark_as_starred, assign_to_folder, trash) apply to the stored sent copy. recipient.* fields match against any recipient — including To, CC, BCC, and SMTP envelope recipients.
Inbound and outbound rules are isolated. Inbound rules never run during sends, and outbound rules never run on message receipt, so stored sent copies aren't re-evaluated against inbound rules.
Rules are evaluated in priority order (lower numbers first). Inbound rules are applied through the recipient grant's policy. Outbound rules are currently evaluated from the sending application's enabled outbound rules. The block action is terminal and cannot be combined with other actions.
Rules support the in_list condition operator, which checks field values against Lists (managed via the Lists API) for dynamic, maintainable allow and block lists. in_list works for from.* and recipient.* fields but not for outbound.type, which accepts only is and is_not.
Rule executions are audited per grant. List evaluation records with GET /v3/grants/{grant_id}/rule-evaluations to see which inbound or outbound rules ran, what normalized input was considered, and which actions were applied.
nylas-pp-cli rules create— Creates a rule for your application. A rule defines atrigger(inboundoroutbound), conditions against sender...nylas-pp-cli rules delete— Deletes the specified rule. This action is irreversible. Policies that reference the rule no longer apply it during...nylas-pp-cli rules get— Returns the specified rule.nylas-pp-cli rules list— Returns a list of all rules for your application.nylas-pp-cli rules update— Updates the specified rule. All fields are optional — only provided fields are updated. The same validation rules...
scheduling — Manage scheduling
nylas-pp-cli scheduling delete-bookings-id— Deletes the specified booking. Nylas also cancels the associated event on the provider. Nylas validates the provided...nylas-pp-cli scheduling delete-session— Deletes a specific session.nylas-pp-cli scheduling get-availability— Gets available time slots within the given time range, using the rules defined in the specified Configuration...nylas-pp-cli scheduling get-bookings-id— Returns the specified Booking object. Nylas validates the provided session ID and uses it to retrieve the related...nylas-pp-cli scheduling import-group-events— Imports existing events to your group events Configuration. You can import up to 20 events per request.nylas-pp-cli scheduling patch-bookings-id— Reschedules the specified booking. Nylas also updates the associated event on the provider. Nylas recommends against...nylas-pp-cli scheduling post-bookings— Books an event with the participants listed in the session's [Configuration...nylas-pp-cli scheduling post-sessions— Creates a new short-lived session that you can pass to the Scheduling Component to enforce user authentication. Your...nylas-pp-cli scheduling put-bookings-id— Confirms or cancels the specified pending booking. Nylas also updates the associated event on the provider. Nylas...nylas-pp-cli scheduling redirect— Redirects an existing v2 Scheduling Page to a v3 URL.nylas-pp-cli scheduling validate-time-slot— Validates whether the selected group event or time slot has changed, and is invalid. This can happen because... -...
templates — Manage templates
nylas-pp-cli templates create-app-level— Creates an application-level template.nylas-pp-cli templates delete-app-level— Deletes the specified application-level template.nylas-pp-cli templates get-app-level— Returns the specified application-level template.nylas-pp-cli templates list-app-level— Returns a list of application-level templates.nylas-pp-cli templates render-html— Renders the HTML content of an application-level template using the provided variables and specified templating engine.nylas-pp-cli templates update-app-level— Updates the specified application-level template.
webhooks — Manage webhooks
nylas-pp-cli webhooks delete-by-id— Delete a webhook destination record.nylas-pp-cli webhooks get-by-id— Get the webhook destinations for an application ID by webhook IDnylas-pp-cli webhooks get-destinations-application— Get a list of all webhook destinations for an application id.nylas-pp-cli webhooks get-mock-payload— Use this endpoint to see example notification payloads for the different Nylas events you specify, to the webhook...nylas-pp-cli webhooks post-destinations— Creates a webhook destination with the specified URL and list of trigger types. ### Webhook destinations and retry...nylas-pp-cli webhooks post-new-secret— Update the webhook secret value for a destination. The previous value will immediately stop being used and the new...nylas-pp-cli webhooks put-by-id— Update the values in a specific webhook destination. ### Limitations - You only need to specify fields that need to...nylas-pp-cli webhooks send-test-event— Use this endpoint to check if your project's webhook destination is configured correctly. Nylas sends a test webhook...
workflows — Manage workflows
nylas-pp-cli workflows create— Creates an application-level workflow. ℹ️ You must have an existing <a...nylas-pp-cli workflows delete— Deletes the specified application-level workflow.nylas-pp-cli workflows get— Returns the specified application-level workflow.nylas-pp-cli workflows list— Returns all application-level workflows.nylas-pp-cli workflows update— Updates the specified application-level workflow.
workspaces — Workspaces group and organize grants in a Nylas application by a common attribute, such as the email address domain (for example, nylas.com).
Assign grants to workspaces
Nylas offers two endpoints to manage workspaces and the grants they contain:
- Automatically Group Grants into Workspaces: Starts a background job that, based on your filters, processes existing grants in your Nylas application and automatically sorts them to existing workspaces. If necessary, Nylas automatically creates new workspaces.
- Update Workspace Assignments: Manually specify a workspace ID and up to 500 grants to add or remove from that workspace.
Workspace limitations
Workspaces are designed to group grants by the top-level domain (TLD) of users' email addresses. Nylas allows you to manually assign grants to any workspace, but that workspace must have
auto_groupset tofalse.When
auto_groupis set tofalse, Nylas doesn't automatically assign grants to that workspace. You'll need to manually assign grants to the workspace using the Update Workspace Assignments endpoint.When
auto_groupistrue, Nylas automatically assigns new grants to the workspace. You can move grants to a different workspace by making an Update Workspace Assignments request.nylas-pp-cli workspaces autogroup— Configures automatic grouping settings for new or existing workspaces, depending on the filters set. If you don't...nylas-pp-cli workspaces create— Creates a workspace.nylas-pp-cli workspaces delete— Deletes the specified workspace.nylas-pp-cli workspaces get— Returns the specified workspace.nylas-pp-cli workspaces get-all— Returns all workspaces in your Nylas application. The application queried is determined based on the API key you use...nylas-pp-cli workspaces update— Updates the specified workspace.
Finding the right command
When you know what you want to do but not which command does it, ask the CLI directly:
nylas-pp-cli which "<capability in your own words>"
which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.
Recipes
Daily inbox triage across every grant
nylas-pp-cli sync --resources messages --since 24h
nylas-pp-cli since 2h --resource messages --agent --select id,subject,from,grant_id,unread | jq '.[] | select(.unread)'
Sync, then filter the mirror to the unread messages since 2h ago — answering 'what changed' from local data.
Find every reference to a topic across mailboxes
nylas-pp-cli search "renewal" --type messages --limit 100 --agent --select grant_id,subject,from,date
FTS5 full-text search across the local mirror; one query spans every connected grant.
SLA dashboard on first-response time
nylas-pp-cli response-time --group-by domain --since 30d --agent --select domain,p50,p90,n
Compute first-response latency from the local thread timeline, grouped by counterparty domain.
Safe send: preview before sending
nylas-pp-cli grants messages send 550e8400-e29b-41d4-a716-446655440000 --to PII_EMAIL_EXAMPLE --subject "Q3" --body "..." --dry-run
nylas-pp-cli grants messages send 550e8400-e29b-41d4-a716-446655440000 --to PII_EMAIL_EXAMPLE --subject "Q3" --body "..." --yes
Two-step send: --dry-run prints the wire payload without calling the API; re-run with --yes to actually send.
Replay a production webhook locally
nylas-pp-cli webhook-replay --since 24h --trigger message.created --to http://localhost:3000/hook
Re-fires every persisted message.created delivery from the last day into your local handler — no production wait required.
Auth Setup
Nylas V3 uses a bearer API key (Authorization: Bearer ) for application-level access to every grant. Set NYLAS_API_KEY in your environment or run nylas-pp-cli auth set-token. For per-user OAuth flows, NYLAS_ACCESS_TOKEN is also supported. The grant_id for each connected mailbox is a path parameter on every per-grant endpoint, not an auth header.
Run nylas-pp-cli doctor to verify setup.
Agent Mode
Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.
Pipeable — JSON on stdout, errors on stderr
Filterable —
--selectkeeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:nylas-pp-cli applications get --agent --select id,name,statusPreviewable —
--dry-runshows the request without sendingOffline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag
Explicit retries — use
--idempotentonly when an already-existing create should count as success, and--ignore-missingonly when a missing delete target should count as success
Response envelope
Commands that read from the local store or the API wrap output in a provenance envelope:
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}
Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.
Agent Feedback
When you (or the agent) notice something off about this CLI, record it:
nylas-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
nylas-pp-cli feedback --stdin < notes.txt
nylas-pp-cli feedback list --json --limit 10
Entries are stored locally at ~/.nylas-pp-cli/feedback.jsonl. They are never POSTed unless NYLAS_FEEDBACK_ENDPOINT is set AND either --send is passed or NYLAS_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
Output Delivery
Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
| Sink | Effect |
|---|---|
stdout |
Default; write to stdout only |
file:<path> |
Atomically write output to <path> (tmp + rename) |
webhook:<url> |
POST the output body to the URL (application/json or application/x-ndjson when --compact) |
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
Named Profiles
A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
nylas-pp-cli profile save briefing --json
nylas-pp-cli --profile briefing applications get
nylas-pp-cli profile list --json
nylas-pp-cli profile show briefing
nylas-pp-cli profile delete briefing -
…(truncated)