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](https://github.com/kiwiz/gkeepapi) (1,600+ stars, actively maintained) — an unofficial reverse-engineered Google Keep client
- Auth via [gpsoauth](https://github.com/simon-weber/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