# List the first 20 personal contacts

> Explore gogcli contacts, other contacts, and directory commands to manage personal, shared, and directory profiles. Access Google People API endpoints with ease.

- Repository: [Peter Steinberger/gogcli](https://github.com/steipete/gogcli)
- Tags: how-to-guide
- Published: 2026-02-16

---

#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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/internal/cmd/contacts.go), the `ContactsCmd` struct defines the available subcommands:

```go
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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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:

```bash

# 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 "grace@example.com" --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:

```bash

# List other contacts (shared Workspace contacts)

gog contacts other list --max 50

# Search other contacts by email

gog contacts other search "john.doe@example.com"

# 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:

```bash

# 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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/internal/outfmt/outfmt.go).
- Service initialization is cleanly separated in [`internal/cmd/contacts_services.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/contacts_services.go) while command definitions reside in [`internal/cmd/contacts.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/contacts.go) and [`internal/cmd/contacts_directory.go`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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.