qfs

qfs

One small grammar for every external service. qfs is a single Rust binary that exposes every backend — the local filesystem, mail, drive, object storage, GitHub, Slack, SQL, git, Google Analytics, Claude, an HTTP fetcher, a directory, and /sys administration — through one uniform, filesystem-shaped, pipe-SQL DSL. The same engine presents three faces: a CLI (and an FTP-like interactive shell), an MCP endpoint for AI agents, and an embedded web dashboard with approval cards. It runs locally or as a self-hosted server (blueprint §1, §11). The Cloudflare Workers wasm32 target is parked while the worker crate is offline (see the blueprint).

qfs generalizes the FTP-shell idea per the blueprint: instead of one FTP-style client for one service, qfs is the closed-core grammar + open registries control plane that the FTP-shell idea generalizes to.

Why qfs exists (the AI payoff)

qfs exists for AI. An agent learns one small grammar and one operating procedure instead of N vendor SDKs:

DESCRIBE <path> → write a qfs statement → PREVIEW → COMMIT

• DESCRIBE a node (qfs describe /mail/drafts) returns its archetype, columns, supported verbs, CALL procedures, prelude aliases, and pushdown — the contract the agent reads first. DESCRIBE is pure: no credentials, no I/O, no network.
• Write a pipe-SQL statement against the node.
• PREVIEW (the default) shows the effect-plan without touching the World.
• COMMIT applies the plan.

The four steps are identical across every backend. That uniformity is the product. The agent's operating procedure ships embedded in the binary — run qfs skill (and qfs skill --examples).

Core model

• Closed core + three open registries (blueprint §3). The language is a closed core — a frozen set of keywords and operators. A new backend adds zero keywords. Everything extensible is a registry entry:
  • paths — a new mount (/mail, /s3, /github, …). See docs/drivers.md.
  • functions / procedures — a registered CALL driver.action(..) + pure prelude aliases.
  • codecs — a registered DECODE/ENCODE format (json, jsonl, yaml, toml, csv, md).
• Four archetypes (blueprint §6). Every node is Blob, Relational, Append, or ObjectGraph; each declares which universal verbs it supports. Unsupported verbs are rejected at parse time, so the agent never plans a rejected op.
• Purity invariant (blueprint §3/§7). Every function/alias produces a Plan and performs no I/O. SEND(d) does not send mail — it desugars to a CALL mail.send node in a Plan. Nothing happens until COMMIT. See docs/language.md.
• Least privilege (blueprint §8). Credentials are stored per layer — an OAuth app registration (cat credentials.json | qfs app add google) and per service account (qfs account add google, or printf %s "$TOKEN" | qfs account add github work) — never inline in a config, a log, or a doc, and a secret value is always piped in via stdin (never argv). Under the hood every secret is envelope-encrypted at rest in the SQLite Project DB: a random data-key encrypts each value, and that data-key is wrapped by the vault's KeyGuardian slots — the passphrase slot qfs init enrolls when it creates the store, plus an optional OS-keychain slot (qfs vault enroll keychain) so this host unlocks without a passphrase. See Connect a service for the per-source steps, and Connections & credentials for the full flow. CREATE POLICY gates writes by verb / path / irreversibility. See docs/server.md.

The shipped surface (three faces, one engine)

The same engine answers on three faces, and the safety model (PREVIEW → COMMIT, the irreversible gate, the policy gate) is identical on all of them:

• CLI — one-shot qfs run / qfs describe, plus the FTP-like interactive shell (no subcommand). See docs/guide/cli.md.
• MCP endpoint — the server exposes the same DESCRIBE → PREVIEW → COMMIT loop as MCP tools so an AI agent drives every service through one contract.
• Web dashboard — an embedded SPA served by qfs serve with approval cards: a human reviews and approves a pending irreversible commit in the browser.

Beyond reads/writes, v0.0.9 ships the operator surface: