Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jasonkneen/openclicky/llms.txt

Use this file to discover all available pages before exploring further.

OpenClicky connects to Google Workspace through gogcli, a local CLI installed as gog. Rather than adding hosted OAuth, a cloud key-sync flow, or a server-side Google login to OpenClicky itself, all Google authentication lives entirely on your machine inside gogcli’s own keyring. The bundled google-workspace-gogcli skill teaches Clicky how to read Gmail, Calendar, Drive, Contacts, Docs, Sheets, Slides, Chat, Tasks, and more — and how to gate any write action behind explicit approval.

​
Why gogcli?

OpenClicky deliberately avoids a hosted Google login because it would require OpenClicky to hold OAuth tokens on a server and add a cloud dependency to a product designed to run locally. gogcli stores credentials in your macOS Keychain (or an encrypted file keyring), so Google tokens never leave your machine. The tradeoff is a one-time CLI setup, but that setup gives you full control over which scopes are granted and which accounts are active.

​
Installation

Install gogcli with Homebrew: 
brew install gogcli
Verify the install: 
gog --version

​
Checking Status

OpenClicky’s Settings → Google panel shows live gogcli status. You can also check from the terminal using the bundled script: 
scripts/check-gogcli-workspace.sh
Or run the checks manually: 
gog --version
gog auth status --json
gog auth list
To see whether accounts are authenticated and which scopes each holds: 
gog --json auth list --check
gog auth credentials list --json

​
Setting Up an OAuth Client

Google Workspace access requires a Desktop OAuth client JSON from a Google Cloud project you control (or that your Workspace organization controls). gogcli stores the client credentials locally — do not commit them to this repository. Store a downloaded client JSON in gogcli: 
gog auth credentials ~/Downloads/client_secret_....json
For a named Workspace client tied to a specific domain: 
gog --client work auth credentials ~/Downloads/work-client.json --domain example.com
If the Google OAuth consent screen shows the app name “Clicky”, that branding comes from the local OAuth client stored in ~/Library/Application Support/gogcli/credentials.json. Replace that file with an OpenClicky-owned Desktop OAuth client JSON and re-authenticate to change the consent-screen app name.

​
Adding Accounts with Scopes

Authorize accounts using the least-privilege scopes required for the task. OpenClicky agents will not request scopes beyond what you authorize here. 
# Read-only Gmail + Drive
gog auth add you@example.com --services gmail,drive --gmail-scope readonly --drive-scope readonly

# Calendar + Tasks (read-only)
gog auth add you@example.com --services calendar,tasks --readonly

# Full user services (only when explicitly needed)
gog auth add you@example.com --services user

​
Workspace-Specific Clients

If you work across multiple Google Cloud projects or Workspace domains, use named clients with aliases: 
gog --client work auth credentials ~/Downloads/work-client.json --domain example.com
gog auth alias set work you@example.com
gog auth alias list
Use --account work or set GOG_ACCOUNT=work in subsequent commands to target the aliased account.

​
Common Read Commands

Use --json for structured output and --account to target a specific account or alias.

​
Gmail

gog gmail search 'newer_than:7d' --account work --json
gog gmail messages search 'from:person@example.com newer_than:30d' --max 10 --json
gog gmail labels list --account work --json

​
Calendar

gog calendar calendars --account work --json
gog calendar events --account work --json
gog calendar search 'project sync' --account work --json
gog calendar freebusy primary --account work --json

​
Drive

gog drive search "name contains 'proposal'" --account work --json
gog drive ls --account work --json

​
Contacts

gog contacts search 'Jane Doe' --account work --json
gog contacts list --account work --json

​
Write Safety

Clicky will never send email, delete files, modify calendar events, alter contacts, post Chat messages, or change admin state without explicit user intent for that specific action.
For write operations, the agent will summarize the target account and the exact mutation before proceeding. Email drafts are shown for approval before any send is attempted. If you have GOG_GMAIL_NO_SEND=1 set in your environment, the agent respects it and bypasses it only for the one approved send: 
env -u GOG_GMAIL_NO_SEND gog --json gmail send \
  --to recipient@example.com \
  --subject 'Subject' \
  --body-file /path/to/approved-body.txt \
  --account work
Useful safety environment variables: 
export GOG_ACCOUNT=work
export GOG_JSON=1
export GOG_GMAIL_NO_SEND=1
# Optional per-task command allowlist:
export GOG_ENABLE_COMMANDS=gmail,calendar,drive,docs,sheets,tasks,contacts

​
Keyring Password

If gogcli is configured to use its encrypted file keyring (rather than the macOS Keychain backend), OpenClicky agents need the keyring password non-interactively. Add it to your local secrets file: 
# ~/.config/openclicky/secrets.env
GOG_KEYRING_PASSWORD=your_keyring_password
The recommended permission setup for this file: 
mkdir -p ~/.config/openclicky
chmod 700 ~/.config/openclicky
$EDITOR ~/.config/openclicky/secrets.env
chmod 600 ~/.config/openclicky/secrets.env
If you encounter keyring issues, run the built-in diagnostic: 
gog auth doctor

​
Troubleshooting

SymptomFix
credentials_exists: falseRun gog auth credentials list --json. If empty, use OpenClicky Settings → Google or run gog auth credentials <client-json>.
No accounts in gog auth listUse OpenClicky Settings → Google or run gog auth add <email> --services ....
Re-auth or missing scopesUse OpenClicky Settings → Google or run gog auth add <email> --services ... --force-consent.
Keyring needs passphraseRun gog auth doctor. Set GOG_KEYRING_PASSWORD in secrets.env or migrate to the macOS Keychain backend.
Command not foundRun GOG_HELP=full gog --help or gog <group> --help to inspect available subcommands.

​
Supported Services

The google-workspace-gogcli skill covers Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Contacts, Tasks, Groups, Workspace Admin, Classroom, Forms, Apps Script, People, and Keep — any service supported by gogcli and the scopes you authorize. Use OpenClicky Settings → Google as the primary status check for day-to-day use.

Build docs developers (and LLMs) love

Get started for freeTalk to us