ko

A personal command-line toolkit for the things I look up or grab all day — papers, X, Hacker News, the web, Google (Sheets/Docs/Calendar/Gmail), documents — without opening a browser tab.

It's opinionated, not generic: each command is a thin wrapper over the one library or API I settled on for that job, with my preferred defaults baked in and only a couple of flags exposed. Built so a human skimming --help and an AI agent calling it from bash get the same clean, pipeable output — plain text / TSV by default, --json when you want structure, errors to stderr. A few of the APIs are paid; at personal scale that's a few dollars a month, and life's too short to reimplement them.

Full docs: kotools.khalido.dev.

The tools

Read & search

AI agents

Google

Make & manage

Utilities: ko doctor (setup status — run it first), ko models (model strings for -m), ko billing (credits left), ko logs, ko mcp (inspect/call MCP servers). Every LLM call prints its cost to stderr — OpenRouter's actual billed cost when available. Agents keep their own markdown memory (plus a shared ~/.config/ko/memory.md about you) and save resumable sessions; ko agent sessions summarize builds a searchable index of them.

It composes

Plain text / TSV by default (add --json for structure), so ko pipes into itself, into ko llm, and into standard tools:

ko hn item 48480978 | ko llm "summarize the debate; what's the consensus?"
ko fetch https://example.com/post | ko llm "key claims as bullets"
ko papers search "retrieval augmented generation" --json | jq -r '.[].doi'
ko x search "claude code" --list ai --days 90     # my AI list, 3 months back

Install

uv tool install kotools     # or one-off, no install: uvx kotools

The package is kotools; the command it installs is ko. Run ko doctor first to see what's set up.

For development (editable clone):

uv tool install --editable /path/to/kotools   # or: uvx --from /path/to/kotools ko --help

API keys

Keys live in environment variables (shell profile or .env) or in ~/.config/ko/config.toml under a [keys] table (env always wins) — never in the repo. ko doctor shows each key's source (env / config / missing). What you need depends on what you use; most of ko works with no keys at all.

Where ko keeps things

Three XDG-style dirs, three jobs (same pattern as gh/opencode; identical on macOS and Linux):

Each is overridable via KO_CONFIG_DIR / KO_STATE_DIR / KO_CACHE_DIR. ko doctor prints all three, plus every effective setting and where it resolved from (env / config / default) — and warns if config.toml is malformed.

Google Sheets setup (one-off) — read & write

ko gsheets runs as you against your Google account (OAuth user flow, no service account). One token grants read and write; reads use the narrower read-only scope under the hood.

Each step below links straight to the right console page. They all take a ?project=<project-id> query param — paste your project's ID (from step 1) into the links, or just keep the project selected in the console's top bar. The gcloud CLI can do step 2; steps 3–4 are console-only.

1. Create a Google Cloud project → https://console.cloud.google.com/projectcreate . Note its project ID (e.g. kotools-500611) — the links below use it.
2. Enable the APIs → API Library: enable Google Sheets, Google Docs (ko gdocs), Google Calendar (ko cal), Gmail (ko gmail — reads are read-only; gmail.compose adds drafts, sending stays opt-in), and Google Drive (the narrow drive.file scope only — see below). ko still can't browse your Drive; one token covers all. Fast path with the gcloud CLI:

   gcloud services enable sheets.googleapis.com docs.googleapis.com calendar-json.googleapis.com gmail.googleapis.com drive.googleapis.com
   

3. Configure + publish the OAuth consent screen → Auth Platform overview (set app name + support email, User type: External), then Audience → Publish app. This step decides whether your refresh token lasts:
   • Workspace org and only need org accounts? User type: Internal — no token expiry, no publish needed. But Internal can't authorize a personal Gmail — use External if you want personal + work.
   • External (any account): a project left in Testing expires its refresh token after 7 days and requires each account added as a Test user. Publish the app to remove both — it stays "unverified" (a warning you click through on your own app), but the token no longer expires.
   • You don't configure scopes here — ko requests them in code (Sheets/Docs/Calendar + Gmail-readonly + Drive drive.file). Adding an API later = one re-auth (ko gsheets auth --logout then ko gsheets auth).
4. Create OAuth credentials → Credentials → Create Credentials → OAuth client ID → Application type: Desktop app → Download the JSON.
5. Save the JSON to ~/.config/ko/google_client.json (or set KO_GOOGLE_CLIENT_FILE=<path>).
6. Run ko gsheets auth. A browser opens; approve (click through the "unverified app" warning). The refresh token caches at ~/.local/state/ko/google_token.json (relocatable via KO_STATE_DIR).

Reuse on other machines: that token file is portable — copy it to another machine's same path (or point KO_STATE_DIR at it) to reuse the auth with no re-consent.

Already authed read-only? ko gsheets auth --logout, then ko gsheets auth to upgrade to read+write.

Write safety. set / put / header / add-tab / new / clear need the read+write grant. The shape-aware writers refuse to overwrite non-empty cells (the error lists exactly which) unless you pass --overwrite — including formulas that currently display blank.

Why OAuth, not a service account? A service account needs every sheet explicitly shared with its email — fine for bots, tedious for a personal read/write-anywhere CLI. OAuth gives access to anything the signed-in account can see. Scope to one folder? No — OAuth scopes are per-API, not per-resource; use a service account with individual share grants if you need tighter control.

Markdown ↔ Google Docs + comments (ko gdocs push/get/comments)

ko requests the narrow drive.file Drive scope — and deliberately not drive/drive.readonly. drive.file grants access only to files ko itself creates or that you open by ID — it still cannot browse, search, or list your Drive. That's exactly enough for a Markdown-first proposal loop, without widening the blast radius:

ko gdocs push proposal.md --title "Acme — Proposal" --folder Proposals   # .md → formatted Doc
# → review & comment in Google Docs (you + colleagues)
ko gdocs comments <doc>                       # read the feedback back (replies indented, [id] shown)
ko gdocs reply <doc> <comment-id> "on it"     # reply to a thread without leaving the terminal
ko gdocs replace <doc> "Q2" "Q3"              # surgical in-place edit — keeps comment threads
ko gdocs push proposal.md <doc>               # re-push edits in place (same URL; diff+confirm, --force skips)
ko gdocs get <doc> -o proposal.md             # pull the Doc back as real Markdown (tables incl.)

# Tabs — per-client shared docs keep one tab per client/topic:
ko gdocs tabs <doc>                           # list tabs (index, title, tabId; sub-tabs indented)
ko gdocs add-tab <doc> "Acme"                 # add a tab (Docs API; refuses a duplicate title)
ko gdocs get <doc> --tab Acme                 # read just that tab (title or tabId, case-insensitive)
ko gdocs append <doc> "note" --tab Acme       # append to one tab's end
ko gdocs replace <doc> "Q2" "Q3" --tab Acme   # scope the replace to one tab (refuses if it'd orphan a comment; --force)

Keep the Markdown in git as the source of truth; push to a Doc for review, export to reconcile. What converts (and what doesn't — code blocks and blockquotes don't): see the tested support matrix in docs/gdocs-markdown.md. --folder takes a folder ID, a /folders/ URL, or a name (Proposals) that ko find-or-creates. Caveat: because drive.file only sees files ko made, get/comments work on docs ko pushed — not on a pre-existing doc someone else created (that returns 404). For broad read access you'd need drive.readonly, which ko intentionally refuses. Images in a pushed doc embed as base64 and don't round-trip cleanly — fine for text proposals.

Multiple Google accounts (work + personal)

ko gsheets supports several accounts — each keeps its own token, and you flip between them.

• Pick the active account (in priority order): --account/-a on any command (ko gsheets -a personal info <id>); the KO_GOOGLE_ACCOUNT env var; or [google] account in ~/.config/ko/config.toml. Unset = "default" (the single-account setup above, unchanged).
• Auth each once: ko gsheets -a work auth then ko gsheets -a personal auth. Tokens cache per account — google_token_work.json, google_token_personal.json (the default account keeps the legacy google_token.json). ko gsheets accounts lists them (* = active).
• OAuth client (the subtle bit). One Desktop client can authorize multiple accounts, so usually a single ~/.config/ko/google_client.json is all you need — just auth each account into it. The exception: if your work account is a Workspace org with an Internal consent screen, that client can't authorize a personal Gmail (and vice-versa). Then give that account its own client from a separate GCP project, saved as google_client_<account>.json (e.g. google_client_personal.json); ko uses the per-account file if present, else falls back to the shared google_client.json.
• Set your usual default with [google] account = "work", and reach for -a personal now and then.

Output conventions

• Default output is human-readable and designed to pipe (ko gsheets get emits TSV, ko arxiv search emits short line format).
• --json everywhere structured data would help. Agents should prefer --json.
• Errors go to stderr. Empty results are not errors — exit 0 with a friendly message.
• Exit codes: 0 success, 1 runtime error (auth, network, API), 2 usage error.

Dev

cd kotools
uv sync
npm install            # pinned wrangler for `ko publish` (needs Node; via fnm/nvm/etc.)
uv run pytest          # offline by default; KO_LIVE_TESTS=1 enables live-API tests
uv run ko --help

Python 3.14, uv, ruff, pytest, typer. Candidate subcommands and design notes: docs/ideas.md.

License

GPL-3.0-or-later. See LICENSE.