qfs-cookbook

Cookbook

Every external service, one language. Mail, a database, a repo, a channel, a bucket — each becomes a tree of paths you query with the same filesystem-shaped pipe-SQL.

::: tip Start here — the one-time setup gates /local, /sys, and local files/repos need no setup. Every cloud service needs a signed-in operator (qfs init — The operator identity; it also creates the encrypted credential store, The QFS passphrase), an authorized account (qfs account add …), and a mount binding that account to a path (qfs connect …). Each chapter's Setup walks through them — without them you can't reach Gmail, Drive, GitHub, Slack, or object storage. :::

One query shape across services

Find the invoices in your inbox, newest first — search a mailbox with where, select, order by, limit:

/mail/inbox
|> where subject LIKE '%invoice%'
|> select date, from, subject
|> order by date DESC
|> limit 20

Learn that shape once and you already know how to read every other service. Swap /mail/inbox for /sql/<conn>/<table>, a /git tree, or a /slack channel and the same where … select … order by … limit pipe just works — that's the whole promise: no per-service API to relearn, one grammar over all of them.

::: tip Reads return rows; writes preview A read runs immediately and returns rows — /local, /sys, a /sql table, and a /git repo all read today. A read of a cloud service you haven't connected (mail, GitHub, Slack, S3, Drive) returns an actionable error telling you exactly which qfs account add … / qfs connect … to run — it never silently fails.

A write (insert, update, upsert, remove, call) previews by default: qfs run shows the plan and changes nothing. Add --commit to act, and --commit-irreversible for things that can't be undone, like sending mail or merging a PR. So paste any recipe and safely see what it would do first. :::

Some sections carry a 🚧 callout marking a part that isn't wired yet — the recipes shown work, but the callout notes what's still coming (today that's object-store writes and reading a git blob's bytes at a @ref).

The chapters

One cookbook per service — each opens with how to connect it, then the recipes that solve common tasks. Jump to the one you need:

• Gmail — search, triage, draft, send, label, and clean up a whole mailbox.
• Google Drive — browse My Drive and Shared Drives, download, upload, create folders, trash.
• Databases — filter, aggregate, update, and set operations over SQL tables.
• git — read a versioned file tree and history, browse it at any ref, record a commit.
• GitHub — list and filter pull requests and issues; merge a PR.
• Slack — read a channel's latest messages; post a message.
• Files & object storage — local files and S3/R2, plus format conversion with codecs.
• Cloudflare (declared) — install and query the declared /cloudflare driver: zones, DNS records, and account-scoped listings written in the query language itself.
• Cross-service — one query spanning several services: join a database to GitHub, a file to a table.
• Automation (server) — turn any query into a trigger, a scheduled job, an HTTP endpoint, or a cached view.
• FAQ & operator reference — how do I connect an account (including a second or different-org Google account), what does PREVIEW mean, why is a read blocked, and which chapter to reach for.

New to qfs? Start with Your first queries and How qfs works.