List the first 20 personal contacts

#gogcli Contacts vs Other Contacts vs Directory: Command Reference for Google People API

The gogcli CLI provides three distinct command groups—gog contacts, gog contacts other, and gog contacts directory—that access separate Google People API endpoints for personal contacts, domain-shared other contacts, and Workspace directory profiles respectively.

The steipete/gogcli tool offers granular control over Google Workspace contact data through differentiated command namespaces. Understanding the distinction between gogcli contacts, other contacts, and directory commands is essential for administrators managing personal contact lists, shared domain contacts, and organization-wide directories.

Understanding the Three gogcli Contacts Command Groups

Personal Contacts (gog contacts)

The primary gog contacts command group manages your personal My Contacts list—contacts you create, edit, and own. According to the source code in internal/cmd/contacts_services.go, this group initializes via newPeopleContactsService, which wraps googleapi.NewPeopleContacts to access the standard Contacts API endpoints.

In internal/cmd/contacts.go, the ContactsCmd struct defines the available subcommands:

type ContactsCmd struct {
    Search    ContactsSearchCmd    `cmd:"" name:"search" help:"Search contacts…"`
    List      ContactsListCmd      `cmd:"" name:"list"   help:"List contacts"`
    Get       ContactsGetCmd       `cmd:"" name:"get"    help:"Get a contact"`
    Create    ContactsCreateCmd    `cmd:"" name:"create" help:"Create a contact"`
    Update    ContactsUpdateCmd    `cmd:"" name:"update" help:"Update a contact"`
    Delete    ContactsDeleteCmd    `cmd:"" name:"delete" help:"Delete a contact"`
    Directory ContactsDirectoryCmd `cmd:"" name:"directory" help:"Directory contacts"`
    Other     ContactsOtherCmd     `cmd:"" name:"other"     help:"Other contacts"`
}

This group supports full CRUD operations: list, search, get, create, update, and delete.

Other Contacts (gog contacts other)

The gog contacts other command group accesses Other Contacts—contacts that belong to your Google Workspace organization but are not in your personal My Contacts list. As implemented in internal/cmd/contacts_directory.go starting at line 38, this uses newPeopleOtherContactsService (line 58), which maps to googleapi.NewPeopleOtherContacts.

Available operations include list, search, and delete. Notably, deleting an other contact requires a two-step process defined in the deleteOtherContact function (starting at line 45): first copying the contact to your My Contacts group via CopyOtherContactToMyContactsGroup, then deleting it from the personal list.

Directory Contacts (gog contacts directory)

The gog contacts directory command group queries the Workspace Directory—domain-wide profiles visible to all organization members. Implemented later in internal/cmd/contacts_directory.go (starting at line 21), this uses newPeopleDirectoryService to access googleapi.NewPeopleDirectory.

Directory operations are read-only: list and search. The command uses a restricted field mask defined by the directoryReadMask constant (line 17), requesting only names and emailAddresses to minimize API quota usage.

Source Code Architecture

Service Layer Implementation

The separation of concerns begins in internal/cmd/contacts_services.go, where three distinct factory functions initialize the respective Google People API clients:

• newPeopleContactsService → googleapi.NewPeopleContacts (personal contacts)
• newPeopleOtherContactsService → googleapi.NewPeopleOtherContacts (other contacts)
• newPeopleDirectoryService → googleapi.NewPeopleDirectory (directory)

Each returns a service interface used by command handlers, ensuring type-safe separation between the three contact domains.

Command Structure Definition

The top-level command structure in internal/cmd/contacts.go embeds both Directory and Other subcommands within the main ContactsCmd struct, while keeping personal contact commands at the top level. This design reflects the API hierarchy: personal contacts are the default view, while directory and other contacts are specialized namespaces.

Practical Usage Examples

Managing Personal Contacts

List your My Contacts with pagination control:

# List the first 20 personal contacts

gog contacts list --max 20

# Search by name or email

gog contacts search "Ada Lovelace"

# Retrieve specific contact details

gog contacts get people/c1234567890

# Create a new contact

gog contacts create --given "Grace" --family "Hopper" --email "[email protected]" --phone "+1-555-1234"

# Update using JSON input

gog contacts update people/c1234567890 --json < updated.json

# Delete with confirmation

gog contacts delete people/c1234567890

Working with Other Contacts

Access domain-shared contacts outside your personal list:

# List other contacts (shared Workspace contacts)

gog contacts other list --max 50

# Search other contacts by email

gog contacts other search "[email protected]"

# Delete an other contact (resource name uses "otherContacts/" prefix)

gog contacts other delete otherContacts/c987654321

Note that other contact resource names use the otherContacts/ prefix rather than people/.

Querying the Workspace Directory

Search domain-wide profiles with restricted field masks:

# List directory entries (names and emails only)

gog contacts directory list --max 100

# Search the directory

gog contacts directory search "engineering"

# Paginate through large directories

gog contacts directory list --page <nextPageToken> --all

All commands support --json for machine-readable output and share pagination flags (--page, --all).

Key Implementation Details

Shared Output and Pagination

All three command groups utilize internal/outfmt/outfmt.go for consistent output formatting. The global --json flag switches between human-readable tables and JSON serialization across personal contacts, other contacts, and directory queries.

Pagination flags (--max, --page, --all) behave identically across all groups, with --all automatically handling pagination tokens to retrieve complete result sets.

Special Handling for Other Contacts Deletion

The deletion workflow for other contacts involves a specific two-step process implemented in internal/cmd/contacts_directory.go. Because the Google People API does not support direct deletion of other contacts, gogcli first copies the contact to the user's My Contacts group using CopyOtherContactToMyContactsGroup, then deletes it using the standard personal contacts delete operation.

This implementation detail explains why other contact resource names use the otherContacts/ prefix while the deletion command ultimately affects the people/ namespace.

Summary

• gog contacts operates on your personal My Contacts list with full CRUD support via googleapi.NewPeopleContacts in internal/cmd/contacts_services.go.
• gog contacts other accesses domain-shared contacts outside your personal list using googleapi.NewPeopleOtherContacts, with a special two-step deletion process via CopyOtherContactToMyContactsGroup.
• gog contacts directory queries the Workspace domain directory via googleapi.NewPeopleDirectory, returning read-only name and email data using the directoryReadMask constant.
• All three groups share common pagination flags (--max, --page, --all) and JSON output handling via internal/outfmt/outfmt.go.
• Service initialization is cleanly separated in internal/cmd/contacts_services.go while command definitions reside in internal/cmd/contacts.go and internal/cmd/contacts_directory.go.

Frequently Asked Questions

What is the difference between gogcli contacts and gogcli contacts other?

The gog contacts command manages your personal My Contacts list—contacts you own and can fully create, read, update, and delete. In contrast, gog contacts other accesses Other Contacts from your Google Workspace domain—contacts shared organization-wide that are not in your personal list. While you can list, search, and delete other contacts, creating or updating them requires first copying them to your personal contacts.

Can I convert an other contact to a personal contact using gogcli?

Yes, though indirectly. When you delete an other contact using gog contacts other delete, gogcli automatically performs a two-step conversion: it first copies the contact to your My Contacts group via CopyOtherContactToMyContactsGroup, then deletes the original. This effectively migrates the contact from the domain-shared other contacts into your personal list before removal.

Why does gogcli directory only show names and email addresses?

The gog contacts directory command uses a restricted read mask defined by the directoryReadMask constant in internal/cmd/contacts_directory.go, which explicitly requests only names and emailAddresses fields. This optimization minimizes Google API quota consumption and aligns with typical directory lookup use cases where full contact details like phone numbers or addresses are not required for domain-wide searches.

Do all three gogcli contacts commands support JSON output?

Yes, all three command groups—gog contacts, gog contacts other, and gog contacts directory—honor the global --json flag. They share the same output formatting logic via internal/outfmt/outfmt.go, allowing you to emit machine-readable JSON instead of human-readable tables for scripting and automation purposes across personal contacts, other contacts, and directory queries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}