Guide

Manage contact groups from the CLI

Contact groups are useful when a script needs named address-book segments instead of a flat list of people. The Nylas CLI exposes the group record operations directly: list groups, create one, rename it, show details, or delete it. It also filters contacts by group with contacts search --group, so this guide covers the group commands, how to list a group's members, and provider-side differences across Google and Microsoft.

Written by Qasim Muhammad Staff SRE

Verified — CLI 3.1.24 · Google, Microsoft · last tested June 23, 2026

Command reference used in this guide: full command reference. For contact records around groups, see manage contacts from the terminal.

How do you list contact groups from the terminal?

List contact groups with nylas contacts groups list. In CLI version 3.1.24, the command accepts an optional grant ID and global output flags such as --json, but no group-specific filter flags. Use show when you already have 1 group ID and need the record details.

The nylas contacts groups list command reads groups for the default account unless you pass a grant ID. JSON output is the safest format for scripts because it preserves full IDs instead of relying on terminal table width. The top-level help lists 5 group subcommands: list, create, show, update, and delete.

# List contact groups for the default account
nylas contacts groups list

# List contact groups as JSON
nylas contacts groups list --json

# Show one contact group by ID
nylas contacts groups show CONTACT_GROUP_ID --json

Google groups usually return IDs that map back to People API contact group resources. Microsoft results should be treated as provider-mapped contact organization data, not as a one-to-one copy of Google groups. Keep the group ID from the command output if you plan to rename, inspect, or delete the same group later.

How do you create and edit a contact group?

Create a contact group with nylas contacts groups create "Name", then rename it with nylas contacts groups update GROUP_ID --name "New Name". Version 3.1.24 prints no create-specific flags and exactly 1 update flag: --name. Delete uses the group ID, with optional --force for noninteractive scripts.

The nylas contacts groups create command takes the group name as the first argument and can also take a grant ID after it. The update command changes the name only, which keeps the terminal flow narrow and predictable. Google's People API also requires group names to be unique and returns HTTP 409 for duplicate names, according to its contactGroups reference.

# Create a new contact group
nylas contacts groups create "2026 Sponsors"

# Rename an existing contact group
nylas contacts groups update CONTACT_GROUP_ID --name "2026 Event Sponsors"

# Delete a contact group with the confirmation prompt
nylas contacts groups delete CONTACT_GROUP_ID

# Delete a contact group without the confirmation prompt
nylas contacts groups delete CONTACT_GROUP_ID --force

Use --force only when your script already confirmed the ID from a previous list or show call. Deleting the wrong group is a provider-side change, not a local cache edit. If you need an audit trail, capture the JSON output and the exact group ID before the delete command runs.

How do Google and Microsoft model contact groups?

Google and Microsoft model contact organization differently. Google exposes first-class contactGroups with names, member counts, and member resource names. Microsoft Graph centers contacts in contact folders and stores categories on contact records. That difference matters in 2026 because a portable CLI command cannot pretend both providers share the same object model.

The Google People API documents contactGroups with create, delete, get, list, and update methods, plus member metadata. Microsoft Graph documents a contactFolder as a folder that contains contacts, and its contact resource includes a categories string collection. The CLI hides some provider differences, but the underlying APIs still differ.

The nylas contacts list command has no group filter in version 3.1.24, but nylas contacts search --group does: pass a group ID to return the contacts in that group (the help lists --group alongside --company, --email, --phone, and --source). Use contacts list with --email, --id, --limit, or --source for non-group lookups. For CSV exports, use the separate export contacts to CSV workflow.

The nylas contacts list command is still useful beside group commands because it returns contact IDs and can limit results. Use --source address_book when you want stored address-book contacts rather than contacts inferred from inbox data. The help text says --limit defaults to 50 and auto-paginates when the requested count is over 200.

# List the contacts in a specific group
nylas contacts search --group CONTACT_GROUP_ID --json

# List contacts with IDs for manual group reconciliation
nylas contacts list --limit 50 --id

# Find one contact by email address
nylas contacts list --email alice@example.com --json

# List stored address-book contacts, not inbox-derived contacts
nylas contacts list --source address_book --limit 200 --json

If your workflow needs adding or removing individual contacts from a group, don't fake it with an undocumented flag. Use the provider API directly, or keep that step in the application layer until the CLI exposes membership changes. The dedupe contacts guide covers record cleanup before you change group data.

Next steps

These 4 links cover the next contact workflows after group records: list contacts, dedupe records, export rows, and check every command flag. Start with the command reference when a script depends on exact syntax, because it mirrors the CLI help surface.