blumkin

Personal Microsoft 365 and Google Workspace skills CLI — named after Rose “Mrs. B” Blumkin, Berkshire’s legendary operator.

blumkin turns your own calendar, mail, and chat into small, invokable skills any coding agent (Cursor, GitHub Copilot, Claude, …) — or a human — can run over the shell, instead of re-implementing OAuth and the Graph / Google API clients each time.

It acts as the signed-in user over delegated OAuth (public client + interactive browser). No server, no app-only permissions, no shared secret. --json on every command for agents.

What it does

One config file, one or more named profiles (Microsoft, Google, or both), selected with --profile or a tag. blumkin skills list --json is the live catalog:

Plus blumkin doctor (setup check), skills / profiles (discovery), upgrade (self-update via pipx / uv tool / an editable checkout), and completion.

Reads work with the base scope set. Anything that reaches another person (mail send, calendar invite, chat message) needs an explicit --yes. Google support is at near-parity with Microsoft — the Google Workspace section below has the exact verb list and the handful of provider differences.

Install (blumkin on PATH)

pipx install blumkin
pipx ensurepath          # first pipx install only; opens a new shell

Then invoke the binary directly — not uv run blumkin:

blumkin --version                       # version, commit, and which binary answered
blumkin auth login                      # once per machine / when cache is cold
blumkin doctor                          # config, token cache, active scope set
blumkin skills list --json              # machine-readable catalog for agents
blumkin calendar today --json
blumkin mail inbox --top 10 --json
blumkin chat last --with "Sam Rivera" --n 3 --json

pipx puts blumkin in its bin dir (usually ~/.local/bin); pipx ensurepath makes sure that is on PATH.

Upgrade

blumkin upgrade

Detects how blumkin is installed and acts to match: pipx upgrade blumkin for a pipx app, uv tool upgrade blumkin for a uv tool, and for an editable -e <path> install (or a bare source checkout) the git pull --ff-only plus --force reinstall a package upgrade cannot do — printed to run yourself, or run for you with blumkin upgrade --yes. from: / to: are the on-disk blumkin --version before and after; an unmanaged install is reported, not touched.

From a clone (developing blumkin)

uv sync --group dev
uv tool install -e .        # editable; `blumkin` now points at the checkout

blumkin --version reports the checkout's commit. blumkin upgrade recognises the editable install and prints (or, with --yes, runs) git pull --ff-only followed by uv tool install -e . --force to re-bake the metadata; blumkin doctor warns when a pull left the installed version stale.

To expose every skill as a typed MCP tool for MCP-aware agents, install the mcp extra (pipx install 'blumkin[mcp]') and run blumkin mcp install — a guided setup that registers blumkin mcp serve with Claude Code, Cursor, and the GitHub Copilot CLI, confirming each. See docs/agent-integration.md.

To use blumkin from agent sessions in other repos (Cursor personal skill, or Copilot CLI instructions), see docs/agent-integration.md. For cutting a release, see docs/RELEASING.md.

Discovering commands

Every group and leaf command has --help with a description and worked examples:

blumkin --help                     # top-level map, common workflows, exit codes
blumkin calendar --help            # a group's commands + typical flows
blumkin calendar create --help     # one command: args, notes, example invocations

blumkin skills list --json is the machine-readable catalog for agents.

Shell completion

blumkin completion <bash|zsh|fish> prints a completion script. Let blumkin install it to the per-user completion dir (idempotent; --force to overwrite, --json reports the path):

blumkin completion bash --install
blumkin completion zsh --install    # then put its dir on $fpath before compinit
blumkin completion fish --install

Or place it yourself — bash-completion v2 lazy-loads this path (no rc edit):

blumkin completion bash > ~/.local/share/bash-completion/completions/blumkin.bash
blumkin completion fish > ~/.config/fish/completions/blumkin.fish

…or source it from your rc file:

blumkin completion bash > ~/.blumkin-complete.bash
echo 'source ~/.blumkin-complete.bash' >> ~/.bashrc
blumkin completion zsh > ~/.blumkin-complete.zsh
echo 'source ~/.blumkin-complete.zsh' >> ~/.zshrc

Open a new shell afterwards. The script calls back into blumkin for completions, so keep it on PATH.

Config (~/.config/blumkin/)

Create ~/.config/blumkin/config.toml (mode 0600). One file, named profiles — one per account, Microsoft or Google — selected with --profile, a tags entry, or BLUMKIN_PROFILE (see blumkin profiles list --json). With more than one profile, blumkin fails closed rather than guessing which account to act as.

default_profile = "work"

[profiles.work]
client_id = "<entra-public-client-id>"
tenant_id = "<your-entra-tenant>"
default_tz = "<IANA timezone, e.g. America/New_York>"
provider = "microsoft"
tags = ["@work", "work", "microsoft", "m365"]

[profiles.personal]
provider = "google"
default_tz = "<IANA timezone>"
google_oauth_client_file = "~/path/to/google-oauth-desktop-client.json"
tags = ["@personal", "personal", "google", "gmail"]

config.toml must use [profiles.<name>]; flat top-level keys are not supported (a config with none configures zero profiles rather than an implicit one).

A top-level [preferences] table sets font_name / font_size / html_email (default true) for every profile; [profiles.<name>.preferences] overrides one profile. A profile value that disagrees with the top-level one for the same key still wins, but blumkin warns about it on stderr:

[preferences]
font_name = "Calibri"
font_size = 11
html_email = true

[profiles.personal.preferences]
font_size = 13  # overrides just this key for this profile

Set tenant_id, default_tz, and provider in the profile table (there are no org-specific code defaults). provider defaults to microsoft when omitted.

Interactive browser auth is public-client only (client_id; plus tenant_id for Microsoft). Do not set a client secret for these flows.

Microsoft token cache files (under profiles/<name>/):

• msal_token_cache.json
• auth_record.json

BLUMKIN_CONFIG_DIR overrides the config directory (not a profile) — useful for an isolated setup or tests. Never commit anything under the config dir.

Google Workspace (provider = "google")

Full walkthrough: docs/google-setup.md (Console project, APIs, consent screen / test users, Desktop client JSON, named profile, login, smoke, troubleshooting).

Short form — point the profile at your Google Cloud Desktop OAuth client JSON (the Console download). That file holds client_id / client_secret; do not put the secret in toml or environment variables. Download that JSON when you create the client — the secret is shown once and Google will not let you re-download it later (recovery means Reset secret / a new client; see docs/google-setup.md §A.4):

[profiles.personal]
provider = "google"
default_tz = "..."
google_oauth_client_file = "~/path/to/google-oauth-desktop-client.json"
tags = ["@personal", "personal", "google", "gmail"]

blumkin auth login records the signed-in address as email = "..." in that profile the first time (display only - it is never used to pick a profile, and never rewritten afterwards). blumkin profiles list shows it, so two profiles are tellable apart at a glance; blumkin doctor warns if the profile is later signed in as a different account.

Optional: set client_id in toml as well; when omitted it is read from the JSON. Keep the client JSON mode 0600 and outside the repo.

Coverage. Google runs auth, all of calendar (update attaches a Meet link instead of a Teams link; create takes the same --repeat recurrence flags), all of mail reads and writes, people resolve (own contacts, plus the Workspace directory on a Workspace account), chat find / last / send / edit / delete / attachments, and docs create (a native Google Doc via the Docs API; --folder targets a folder blumkin itself created). meeting get / meeting transcription are stubbed by design — Google Meet transcript access is deliberately not implemented (docs/DECISIONS.md D8). A few option-level combinations also still fail closed on a Google profile: mail list / mail inbox --importance / --has-attachments / --orderby, and calendar suggest --treat-tentative free. Everything else fails closed with a clear error.

Provider differences.

• mail folders lists Gmail labels that act as folders; mail list --folder still takes the well-known names.
• Mail writes need the gmail.compose scope — re-run blumkin auth login once after upgrading or those calls exit 4 (missing_scope).
• Chat attachments are listed but Drive-backed files are not downloadable.
• A returned draft id is the Gmail draft id; attachments[].id is null (Gmail carries attachments inside the raw message).

Token file (written by blumkin auth login): profiles/<name>/google_token.json. graph_timeout_seconds in toml bounds Google HTTP and token-refresh calls too. Never commit any of these files.

Tests

uv run pytest -m 'not live'                        # CI-equivalent (mocks / offline)
BLUMKIN_LIVE=1 uv run pytest -m live               # live Graph reads + silent refresh
BLUMKIN_LIVE_GOOGLE=1 uv run pytest -m live_google # live Google reads (Google profile)

Live tests need ~/.config/blumkin/ by default (override with BLUMKIN_CONFIG_DIR): config.toml, token cache, auth record, and a usable refresh token. The live_google tests instead need a logged-in Google profile (provider = "google"). Never commit those files.

Security

blumkin acts as you over delegated OAuth — no server, no shared secret, no one else's data. Auth and config live only under ~/.config/blumkin/ and are never committed.

• docs/SECURITY-AT-A-GLANCE.md — one page: what it touches, the auth model, blast radius, how releases are trusted.
• SECURITY.md — full policy, response targets, and private vulnerability reporting.

Docs

• PLAN.md — CLI design
• docs/DECISIONS.md — standing decisions and the design-artifact index
• CONTRIBUTING.md — review model and the static-analysis / scanning toolchain
• HANDOFF.md — session handoff
• AGENTS.md — contributor / agent ground rules
• RETROSPECTIVE-M1.md — M1 ship retrospective (#11)
• docs/agent-integration.md — using blumkin from Cursor / Copilot CLI, and the frozen skills list --json contract
• docs/operator-config.md — optional ~/.config/blumkin/*.md operator-context files (email-context.md)
• docs/RELEASING.md — release flow, PyPI trusted publishing, rollback
• docs/google-setup.md — Google Cloud Desktop OAuth + blumkin Google profile
• .cursor/skills/blumkin/SKILL.md — Cursor agent skill

License

MIT — see LICENSE.