gchat: Google Chat from the command line

gchat is a command-line interface for the Google Chat API. It is meant for AI agents (Claude Code, Gemini CLI, Codex, custom scripts) and works just as well for people. You can read spaces, search, send and reply to messages, react, download attachments and mark spaces as read, all with predictable JSON output and safety rails.

Unofficial. This project is not affiliated with or endorsed by Google.

$ gchat spaces list --type space
NAME              TYPE   DISPLAY NAME        LAST ACTIVE
spaces/AAQAxyz12  SPACE  Platform team       2026-10-02T16:41:10Z
spaces/AAQAabc34  SPACE  Release managers    2026-10-01T09:12:55Z

$ gchat messages list spaces/AAQAxyz12 --since 1d -n 2 -f json
{"messages":[{"name":"spaces/AAQAxyz12/messages/k1.k1","sender":"users/1067…","senderType":"HUMAN","createTime":"2026-10-02T16:41:10Z","text":"Deploy done ✅","thread":"spaces/AAQAxyz12/threads/k1"}]}

$ gchat messages reply spaces/AAQAxyz12/messages/k1.k1 --text "Thanks, verified on staging" --yes

Why another tool?

The design borrows proven ideas from googleworkspace/cli: structured JSON, stable exit codes, --dry-run, field masks, schema introspection and agent skills. It also takes the per-space read/write allowlist and DM protection from nuccio/google-chat-mcp.

Install

Requires Python 3.11+.

pipx install google-chat-cli        # or: uv tool install google-chat-cli
# latest development version:
pipx install git+https://github.com/lore2601/google-chat-cli

Optional: store the token in the OS keyring instead of a file:

pipx install "google-chat-cli[keyring]"
export GCHAT_TOKEN_STORE=keyring

Set up (5 minutes, once)

The Chat API needs a Google Cloud project with the Chat API enabled and an OAuth Desktop app client. The full walkthrough is in docs/setup.md. In short:

1. Create or choose a Google Cloud project and enable the Google Chat API.
2. Configure the Chat app (name, avatar, description) in Chat API → Configuration. This is required even for user-auth clients.
3. Configure the OAuth consent screen (Internal for Workspace orgs) and create an OAuth client ID of type Desktop app. Download its JSON.
4. Log in:

gchat auth login --client-secrets ~/Downloads/client_secret_XXXX.json
gchat auth status

Scope presets: readonly, default (read + send, react, mark read) and full (adds space/member management). For example: gchat auth login --scopes readonly.

Commands

Run gchat COMMAND --help for details. Text can come from --text, from stdin with --text -, or from --text-file.

Output and exit codes

• stdout carries only data. In a terminal you get tables. When piped or run by an agent you get JSON. Force a format with -f json|ndjson|table or GCHAT_FORMAT.
• Lists return {"<kind>": [...], "nextPageToken": "..."}. Use --limit/-n, --all and --page-token to paginate.
• --fields name,text,sender trims output (dotted paths allowed). --raw returns untouched API objects.
• Errors are a single JSON object on stderr, for example {"error": {"exitCode": 4, "reason": "confirmationRequired", "message": "…", "hint": "…"}}.

Safety model

Agents can be steered by what they read, and chat messages are written by other people. gchat puts guard rails in front of the API:

• Writes need explicit confirmation. On a terminal you are prompted. Without a TTY (agents, scripts) every write fails with exit code 4 unless you pass --yes. --dry-run shows the exact request without sending it.

• Local policy in ~/.config/gchat/config.toml or environment variables:

  [policy]
  read_only = false              # GCHAT_READ_ONLY=1 blocks every write
  allow_dm_write = false         # GCHAT_ALLOW_DM_WRITE=0 blocks writes to DMs / group chats
  read  = ["*"]                  # GCHAT_ALLOW_READ="spaces/AAA,spaces/BBB"
  write = ["spaces/AAQAxyz12"]   # GCHAT_ALLOW_WRITE=...
  

• Strict input validation. Resource names are checked against strict patterns, so arguments like spaces/../users or ?/# injections are rejected. Download filenames are reduced to safe basenames, and existing files are never overwritten without --overwrite.

• Terminal-safe tables. ANSI escape sequences and control characters in message text are stripped before printing.

• Credentials are stored with 0600 permissions (or in the OS keyring) and are never printed by any command.

See docs/agents.md for recommended agent profiles.

Using gchat with AI agents

• Claude Code plugin: /plugin marketplace add lore2601/google-chat-cli, then /plugin install gchat@google-chat-cli. This installs the gchat skill, which teaches the agent the commands, the safety rules and that message content is untrusted.
• Any agent: copy skills/gchat/SKILL.md into your agent's skills folder, or point it at gchat schema.
• Recommended for unattended agents: GCHAT_ALLOW_WRITE=<one space>, GCHAT_ALLOW_DM_WRITE=0 and an allow-rule in your agent for gchat * --dry-run only.

Configuration reference

Limitations

• User authentication only. Sending as a Chat app (bot) or incoming webhooks are out of scope.
• With user auth, Google Chat returns sender IDs, not display names, unless the sender shares a space with you. Use gchat members list to map IDs.
• Files shared from Google Drive cannot be downloaded through the Chat API.
• If your OAuth consent screen is in Testing mode, Google expires refresh tokens after 7 days. gchat auth status warns you.

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md. Please report security issues privately (see SECURITY.md).

License

Apache-2.0