Google Keep

Read, create, edit, search, and manage Google Keep notes and lists via CLI.

Google Keep CLI Skill

Manage Google Keep notes and lists from the command line using the unofficial gkeepapi.

Setup

After installing, the CLI lives in the skill directory. Set up a convenience alias or wrapper:

bash

SKILL_DIR="<path-to-this-skill>"  # e.g. skills/google-keep
alias gkeep="$SKILL_DIR/.venv/bin/python3 $SKILL_DIR/gkeep.py"

Or create a global wrapper:

bash

cat > ~/.local/bin/gkeep << 'EOF'
#!/bin/bash
SKILL_DIR="$(dirname "$(readlink -f "$0")")/../.openclaw/workspace/skills/google-keep"
exec "$SKILL_DIR/.venv/bin/python3" "$SKILL_DIR/gkeep.py" "$@"
EOF
chmod +x ~/.local/bin/gkeep

Authentication

First-time setup (OAuth token exchange):

1. Go to https://accounts.google.com/EmbeddedSetup in your browser
2. Log in with your Google account
3. Click "I agree" on the consent screen (page may spin forever — ignore it)
4. Open DevTools: F12 → Application tab → Cookies → accounts.google.com
5. Copy the value of the oauth_token cookie
6. Run:

bash

gkeep auth <email> <oauth_token>

With pre-obtained master token:

bash

gkeep auth-master <email> <master_token>

Credentials are stored in <skill-dir>/.config/ (chmod 600). The master token has full account access — treat it like a password. It does not expire (unlike standard OAuth refresh tokens).

Commands

List notes

bash

gkeep list                    # Active notes
gkeep list --archived         # Include archived
gkeep list --pinned           # Pinned only
gkeep list --label "Shopping" # Filter by label
gkeep list --json             # JSON output
gkeep list -v                 # Show IDs

Search

bash

gkeep search "grocery"
gkeep search "todo" --json

Get a specific note

bash

gkeep get <note-id>
gkeep get "Shopping List"     # By title (case-insensitive)
gkeep get <id> --json

Create notes

bash

gkeep create --title "Ideas" --text "Some thoughts"
gkeep create --title "Groceries" --list --items "Milk" "Eggs" "Bread"
gkeep create --title "Important" --pin --color Red --label "Work"

Edit notes

bash

gkeep edit <id-or-title> --title "New Title"
gkeep edit <id-or-title> --text "Updated text"
gkeep edit <id-or-title> --pin true
gkeep edit <id-or-title> --archive true
gkeep edit <id-or-title> --color Blue

List operations

bash

gkeep check "Groceries" "milk"           # Check off an item
gkeep check "Groceries" "milk" --uncheck # Uncheck
gkeep check "Groceries" "m" --all        # Check all matching
gkeep add-item "Groceries" "Butter" "Cheese"  # Add items

Delete (trash)

bash

gkeep delete <id-or-title>

Labels

bash

gkeep labels              # List all labels
gkeep labels --json

Export / backup

bash

gkeep dump                # All notes as JSON
gkeep dump > backup.json

Colors

Valid colors: White, Red, Orange, Yellow, Green, Teal, Blue, DarkBlue, Purple, Pink, Brown, Gray

How it works

• Uses gkeepapi (1,600+ stars, actively maintained) — an unofficial reverse-engineered Google Keep client
• Auth via gpsoauth — Google Play Services OAuth flow to obtain a master token
• State is cached locally (.config/state.json) for fast startup after the initial sync
• Master tokens don't expire, so no re-auth dance
• Unofficial API — Google could break compatibility at any time (but gkeepapi has been stable for years)

Security notes

• The master token grants full access to the associated Google account
• Credentials are stored with 600 permissions in .config/
• Never commit .config/ to version control
• delete moves notes to trash (recoverable) — it does not permanently delete