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:

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:

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:

gkeep auth <email> <oauth_token>

With pre-obtained master token:

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

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

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

Get a specific note

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

Create notes

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

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

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)

gkeep delete <id-or-title>

Labels

gkeep labels              # List all labels
gkeep labels --json

Export / backup

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