How to Automate Google Contacts Management from the Command Line?

The Problem: Manual Contact Management is a Bottleneck

You're building an AI agent that needs to interact with a user's Google Workspace environment. Perhaps it's a scheduling assistant that needs to look up colleagues' contact details, a CRM bot that syncs new leads, or an onboarding agent that creates contacts for new team members. The core task seems simple: read, create, or update a contact in Google People.

But the moment you start implementing, the friction begins. You need to handle OAuth2 authentication flows, manage API quotas, parse complex JSON response structures, and deal with pagination. Writing and maintaining this boilerplate code for every agent that touches contacts becomes a significant time sink. The problem isn't just the initial development; it's the ongoing maintenance. When the Google People API updates its schema or deprecates a field, your agent's contact functionality breaks, requiring urgent patches.

This manual, code-heavy approach creates several pain points:

• Development Overhead: Significant time is spent on API plumbing instead of core agent logic.
• Fragility: Direct API calls are tightly coupled to specific API versions, making updates risky.
• Inconsistency: Different agents might implement contact operations in slightly different ways, leading to bugs and maintenance headaches.
• Security Complexity: Properly securing OAuth tokens and handling scopes for each agent is non-trivial.

A good solution would abstract away the API complexity, provide a stable and consistent command-line interface, handle authentication centrally, and allow your AI agent to perform contact operations with simple, reliable commands.

Introducing a Practical Solution: The gws-people CLI Skill

One option to address this is the gws-people skill. It's part of the Google Workspace CLI (gws), a larger toolkit for interacting with Google services. This skill provides a command-line interface specifically for the Google People API, allowing you to manage contacts and profiles without writing direct API client code.

The core idea is to let your AI agent execute shell commands like gws people contacts create --json '{...}' instead of making HTTP requests. The CLI handles authentication, request formatting, and response parsing. This shifts the burden from your agent's codebase to a maintained, external tool.

How Does It Work? A Closer Look

The skill exposes the Google People API's resources and methods as CLI subcommands. Before using any method, you can inspect its requirements using the built-in help and schema commands. This is a crucial step for any agent builder to understand what data is needed.

For example, to see what parameters are required to create a contact, you would run:

gws schema people.contacts.createContact

This command outputs the expected JSON structure, required fields, and data types, which your agent can use to construct valid requests.

Key Capabilities and Boundaries

The skill covers the main operations of the Google People API:

• Contact Management: Create, read, update, and delete individual contacts (people.contacts.*).
• Batch Operations: Create or update multiple contacts in a single call (people.batchCreateContacts, people.batchUpdateContacts), which is efficient for syncing data.
• Contact Groups: Manage groups (like "Friends" or "Work") (contactGroups.*).
• Other Contacts: Access auto-created contacts from interactions (otherContacts.*).
• Directory Search: Search your organization's directory (people.searchDirectoryPeople).

Important Boundaries:

• It does not manage Google Contacts' "My Contacts" list directly; that's handled through the otherContacts resource.
• Photo operations (updateContactPhoto, deleteContactPhoto) are available but may have specific size and format constraints.
• The skill relies on the gws CLI's shared authentication module. You must set up OAuth2 credentials and scopes (like contacts or contacts.other.readonly) beforehand, as outlined in the shared skill documentation.
• It is a low-security level skill. This means it's designed for standard use cases but may not be suitable for handling highly sensitive contact data without additional review of your agent's environment and access controls.

When Should You Consider This Skill?

This skill is worth inspecting if your workflow matches these scenarios:

1. You are building multiple AI agents that need to interact with Google Contacts. Using a common CLI tool promotes consistency and reduces duplicated code.
2. Your agent's primary logic is not contact management. If contacts are just one data source among many (e.g., for a calendar scheduling agent), offloading this to a CLI keeps your agent's codebase focused.
3. You prefer shell-based automation. If your agent's architecture is based on executing system commands (common in some AI agent frameworks), this fits naturally.
4. You need to perform batch operations for initial data loads or periodic syncs.

When Might It Not Be the Best Fit?

• High-Frequency, Low-Latency Needs: If your agent needs to make dozens of contact lookups per second within a tight latency budget, the overhead of spawning a CLI process for each call might be prohibitive. Direct API calls or a dedicated client library could be faster.
• Complex, Stateful Workflows: If your agent needs to maintain a long-lived connection or stream real-time contact changes, a CLI tool designed for discrete commands is not ideal.
• Custom Authentication Flows: If your agent operates in an environment where the standard gws OAuth2 flow (browser-based or service account) doesn't work, you'll need to handle authentication separately.

What to Inspect Before Using It

Before integrating this skill into your agent, perform these checks:

1. Repository Health: The skill lives in the googleworkspace/cli repository. Check its activity, open issues, and recent commits. With over 27k stars, it's a well-established project, but always verify it's actively maintained.
2. License: The repository uses a LICENSE file. Review it to ensure it's compatible with your project's licensing requirements.
3. Dependencies: The skill requires the gws binary. Ensure you can install and run it in your agent's execution environment (e.g., a Docker container, a cloud function runtime).
4. Authentication Setup: Read the shared skill documentation (gws-shared/SKILL.md) thoroughly. You must configure OAuth2 credentials and grant the necessary scopes. Test this setup manually with a simple command like gws people contacts list before building it into your agent.
5. Error Handling: Understand how the CLI reports errors (exit codes, stderr messages). Your agent will need to parse these to handle failures gracefully (e.g., contact not found, permission denied, rate limit exceeded).
6. Performance Profile: Run a few sample commands and measure the execution time. Does it meet your agent's performance requirements?

A Practical Example: Creating a Contact

Let's say your agent receives a new lead's information and needs to add it to Google Contacts. Using the gws-people skill, the agent could execute a command like this:

gws people contacts createContact --json '{
  "names": [{"givenName": "Alex", "familyName": "Chen"}],
  "emailAddresses": [{"value": "alex.chen@example.com"}],
  "organizations": [{"name": "Example Corp", "title": "Product Manager"}]
}'

The CLI would handle the API call and return a JSON response with the newly created contact's resource name and details. Your agent can then parse this response to confirm success or handle any errors.

Conclusion

The gws-people skill offers a practical way to offload Google Contacts management from your AI agent's codebase to a maintained command-line tool. It's particularly useful when you need consistent, scriptable access to contacts across multiple agents or when your agent's architecture favors shell commands.

However, it's not a universal solution. Evaluate its performance characteristics, authentication requirements, and fit with your agent's specific needs. By inspecting the repository, testing the setup, and understanding its boundaries, you can make an informed decision about whether this skill solves your contact management bottleneck effectively.