Manage Contacts from Terminal

Command references used in this guide: nylas contacts list, nylas contacts search, nylas contacts create, and nylas contacts show.

Why manage contacts from the terminal?

Managing contacts from the terminal means listing, searching, creating, and updating your address book without opening a browser or GUI app. The Google People API requires OAuth credentials, a GCP project, and 40+ lines of Python to list contacts. Microsoft Graph needs an Azure AD app registration and a 3-step token flow. The Nylas CLI wraps both behind a single command that returns JSON in under 2 seconds.

Sales teams typically manage hundreds to thousands of contacts per rep. Keeping that data accurate means frequent updates, deduplication, and exports. Doing it from the terminal lets you script those tasks with jq, pipe output into CRM imports, and run bulk updates from a shell loop. No clicking through paginated web UIs one record at a time.

Install the CLI with Homebrew (brew install nylas/nylas-cli/nylas) and run nylas init to connect your account. For other install methods, see the getting started guide. Authentication takes about 2 minutes via an OAuth browser flow that handles Gmail, Outlook, and 4 other providers.

How do you list and search contacts?

The nylas contacts list command fetches contacts from whichever provider you authenticated during nylas init. It returns 10 results by default, sorted alphabetically. Adding --json gives you structured output with name, email, phone, company, and any custom fields the provider stores. Gmail contacts include Google-specific fields like resourceName; Outlook contacts include categories.

Searching narrows results to contacts matching a name, email, or company string. The --query flag sends the search to the provider's native contact search engine, so Gmail searches behave like the Google Contacts search bar and Outlook searches match against the Global Address List. Search typically completes in 300-500ms for address books under 5,000 contacts.

# List your first 10 contacts
nylas contacts list

# List 25 contacts as JSON
nylas contacts list --limit 25 --json

# Search for contacts by name or email
nylas contacts search --query "alice@example.com"

# Search by company name
nylas contacts search --query "Stripe" --json

# View a single contact's full details
nylas contacts show CONTACT_ID

The --json output includes every field the provider returns: email addresses (up to 3 per contact on Gmail), phone numbers, physical addresses, job titles, and company names. The field names follow conventions from the vCard standard (RFC 6350). Pipe it into jq to extract just the fields you need. Outlook stores contacts as Graph contact resources with fields like givenName, surname, and emailAddresses. The CLI normalizes these into a consistent JSON structure across Gmail and Outlook, so scripts don't need provider-specific parsing logic.

How do you create and update contacts?

Creating a contact from the terminal takes one command with --name and --email flags. The contact is created in the provider's address book immediately. On Gmail, it appears in Google Contacts within 1-2 seconds. On Outlook, it lands in the default Contacts folder. The command returns the new contact's ID, which you can use for subsequent updates or to add it to a group.

Updating works the same way: pass the contact ID and the --name flag with the new value. The command accepts one field at a time. This is useful for bulk operations. A shell loop over a CSV file can update 100 contacts in under 30 seconds, which would take 15-20 minutes of manual clicking in a web UI.

# Create a new contact
nylas contacts create --name "Alice Chen" --email alice@example.com

# Create with additional fields
nylas contacts create \
  --name "Bob Smith" \
  --email bob@company.com

# Update an existing contact's name
nylas contacts update CONTACT_ID --name "Jane Doe-Smith"

# Delete a contact
nylas contacts delete CONTACT_ID

For bulk creation, write a shell script that reads from a CSV and loops through each row. The API rate limit is 5 requests per second on most providers, so inserting 500 contacts takes about 100 seconds. Add a sleep 0.2 between calls if you hit 429 responses. The CLI prints the created contact ID to stdout, so you can capture them in a log file for auditing.

How do you manage contact groups?

Contact groups (called “labels” in Gmail and “categories” in Outlook) let you organize contacts into named collections. The Nylas CLI exposes group management through the contacts groups subcommand. Gmail supports up to 500 contact groups per account, according to the Google People API documentation. Outlook supports up to 250 categories.

Listing groups shows every group in the connected account with its ID and member count. Creating a group is a single command. Adding contacts to a group uses the group ID and one or more contact IDs. This is particularly useful for segmenting contacts before a bulk email send or for organizing imported contacts by source.

# List all contact groups
nylas contacts groups list

# List groups as JSON with member counts
nylas contacts groups list --json

# Create a new contact group
nylas contacts groups create "Q2 Prospects"

# Sync contacts from the provider
nylas contacts sync

Group membership syncs bidirectionally. If you add a contact to a group via the CLI, it appears in the Gmail or Outlook web UI under that label or category. The sync happens through the provider's API, not a local database, so changes are visible across all devices within 5-10 seconds.

A common workflow is creating groups for sales pipeline stages: “Cold Leads”, “Contacted”, “Meeting Booked”, “Closed”. As contacts move through the funnel, update their group membership from a script. The CLI returns group IDs in JSON format, so you can map group names to IDs in a lookup table and automate the transitions based on email reply status or calendar events.

How do you export contacts to CSV?

Exporting contacts to CSV is a jq one-liner piped from nylas contacts list --json. The JSON output contains all contact fields, and jq's @csv filter handles quoting, escaping commas in names, and encoding special characters. A typical address book of 500 contacts exports in 3-5 seconds depending on API response time.

The examples below cover three common export scenarios: a simple name-and-email list for mail merge, a full export with phone and company for CRM import, and a filtered export that only includes contacts from a specific company domain. Each produces a standard CSV that opens in Excel, Google Sheets, or any CRM import wizard.

# Export name and email to CSV
nylas contacts list --json --limit 500 | \
  jq -r '.[] | [.given_name, .surname, .emails[0].email] | @csv' \
  > contacts.csv

# Full export with phone and company
nylas contacts list --json --limit 500 | \
  jq -r '["Name","Email","Phone","Company"],
  (.[] | [
    ((.given_name // "") + " " + (.surname // "")),
    (.emails[0].email // ""),
    (.phone_numbers[0].number // ""),
    (.company_name // "")
  ]) | @csv' > contacts-full.csv

# Export only contacts from a specific domain
nylas contacts list --json --limit 500 | \
  jq -r '.[] | select(.emails[0].email | test("@company\.com$")) |
  [.given_name, .surname, .emails[0].email] | @csv'

For recurring exports, wrap the command in a cron job. A weekly export to a shared drive keeps your CRM in sync without manual effort. The --limit flag controls how many contacts are fetched per call. For address books larger than 1,000 entries, paginate by running multiple calls with offset parameters and concatenating the results.

The same JSON output works for deduplication. Pipe contacts through jq to group by email address, identify duplicates, and output a report. Address books with 1,000+ entries typically have a 5-12% duplication rate, according to a 2023 Validity data quality report. Catching those duplicates before a bulk send avoids sending the same message twice to the same person.

# Find duplicate contacts by email address
nylas contacts list --json --limit 500 | \
  jq -r '[group_by(.emails[0].email) | .[] | select(length > 1) |
  {email: .[0].emails[0].email, count: length,
   names: [.[].given_name]}]'

Next steps

• Enrich contacts from email — auto-populate contact fields by parsing email signatures and headers
• Organize emails by company — group inbox messages by the sender's company domain
• CRM email workflows — connect contacts and email threads to CRM pipeline stages
• Full command reference — every flag and subcommand documented