grokko 0.1.0

CLI to access Grok

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=[e-mail] 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=[e-mail]
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