Grokko

CLI for capturing Grok session cookies, triggering account exports, polling email for export links, downloading the ZIP, and inspecting export contents.

Install

Requires Python 3.10+ and uv.

git clone https://github.com/deeplook/grokko
cd grokko
uv tool install .
grokko setup

grokko setup installs the Playwright browser dependencies, skipping the download if a compatible version is already present.

To install into a local virtual environment instead:

git clone https://github.com/deeplook/grokko
cd grokko
uv venv ./myenv
uv pip install --python ./myenv .
./myenv/bin/grokko setup

Plugins

grokko can load optional command plugins from installed packages via the grokko.plugins entry-point group. Plugins are discovered automatically at startup — no configuration needed beyond installation.

Installing plugins

If you installed grokko as a uv tool, add a plugin by reinstalling with --with (works for both a fresh install and an existing one):

uv tool install --reinstall --with grokko-plugin .

For a local plugin directory, pass the path instead of a package name:

uv tool install --reinstall --with ../grokko-plugin .

Or use the Makefile shorthand from the grokko directory:

make install-tool PLUGINS="grokko-plugin"

If you installed grokko as a regular package (e.g. uv pip install grokko or pip install grokko), install the plugin into the same environment:

pip install grokko-plugin

Writing plugins

In a plugin package, expose either a Typer app or a single command callback:

[project.entry-points."grokko.plugins"]
reports = "my_package.cli:app"
details = "my_package.extra:inspect_extra"

If app is a typer.Typer() instance, grokko reports ... becomes a command group. If inspect_extra is a callable command, grokko details becomes a single command.

Quick Examples

Capture cookies from your local Chrome profile:

grokko session capture

Trigger an export, poll IMAP for the export email, and download the ZIP:

IMAP_USER=you@example.com IMAP_PASSWORD=app-password grokko export run

Show the latest chat transcript:

grokko chat --messages

Show a range of chat summaries by recency index:

grokko chat -n 3:10

The START:STOP form is half-open, so 3:10 means indices 3 through 9.

Download all attachments from a conversation (uploaded files and generated images):

grokko chat --id <conversation-id> --attachments

Files are saved to ~/.grokko/attachments/<id>/ by default. Override with --attachments-dir:

grokko chat --id <conversation-id> --attachments --attachments-dir ./my-dir

Combine with --messages to download attachments and print the transcript in one go:

grokko chat --id <conversation-id> --attachments --messages

Inspect the most recently downloaded ZIP:

grokko export inspect

Extract a Grok export ZIP to Obsidian Markdown notes:

grokko extract export.zip ./notes

Export only starred conversations:

grokko extract export.zip ./notes --starred

Export with attachments:

grokko extract export.zip ./notes --attachments all

See an overview of all CLI commands:

grokko overview

The CLI stores its working files in ~/.grokko by default. Override that with GROKKO_STORAGE_DIR=/path/to/dir if needed.

Environment

Required for grokko export run:

IMAP_USER=you@example.com
IMAP_PASSWORD=app-password

Optional:

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
GROK_EXPORT_SUBJECT="Your data export is ready"
GROK_EXPORT_SENDER=
GROK_EXPORT_URL_PATTERN='https://accounts\.x\.ai/download/\?file_reference=[\w/-]+\.zip'
GROK_EXPORT_MAILBOX=INBOX
GROK_EXPORT_POLL_INTERVAL=30
GROK_EXPORT_POLL_TIMEOUT=600
GROKKO_STORAGE_DIR=~/.grokko

Development

make test
make lint
make format

Install and run the pre-commit hooks:

uv run pre-commit install
uv run pre-commit run --all-files

License

MIT