qfs

qfs

One small grammar for every external service. qfs is a single Rust binary that exposes every backend — mail, drive, object storage, GitHub, Slack, SQL, git, Google Analytics — through one uniform, filesystem-shaped, pipe-SQL DSL. It runs as a CLI locally, as a daemon on EC2, or (target) compiled to wasm32 for Cloudflare Workers (RFD-0001 §1, §9).

qfs generalizes the FTP-shell idea per RFD-0001: 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 (RFD §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 (RFD §5). 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 (RFD §3/§6). 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 (RFD §10). Credentials are stored per driver/account (qfs account add), never inline in a config, a log, or a doc. CREATE POLICY gates writes by verb / path / irreversibility. See docs/server.md.

Install

# Download, verify the sha256, and install the matching tarball for your OS/arch:
curl -fsSL https://raw.githubusercontent.com/qmu/qfs/main/packages/qfs/install.sh | sh
qfs --version

install.sh detects your OS + arch, downloads the matching release tarball, verifies its sha256 before extracting, and installs qfs to ~/.local/bin (override with QFS_INSTALL_DIR). Releases ship static Linux (x86_64/aarch64 musl) + macOS (x86_64/aarch64) binaries; see Releases & distribution.

Or build from source (requires a Rust toolchain):

cd packages/qfs && cargo build --release    # the native binary at packages/qfs/target/release/qfs

After installing, install.sh prints a short Next steps guide (try it, connect a service, update, and where to read more). The Quickstart below is the same loop.

Quickstart (the loop)

# 1. DESCRIBE a node — pure, no creds, offline:
qfs describe /mail/drafts

# 2. write + 3. PREVIEW (default — shows the plan, touches nothing):
qfs run "FROM /mail/inbox |> WHERE subject LIKE '%invoice%' |> SELECT subject, from"

# create a draft (PREVIEW first, then COMMIT to apply):
qfs run "INSERT INTO /mail/drafts VALUES (...)"            # PREVIEW
qfs run "INSERT INTO /mail/drafts VALUES (...) COMMIT"     # apply

# 4. COMMIT an irreversible effect requires an explicit ack in one-shot:
qfs run "id:draft-1 |> CALL mail.send COMMIT" --commit-irreversible

The interactive shell (no subcommand) gives the same loop with an FTP-like prompt:

qfs            # ls / cd / cat / cp / rm … all desugar to the same pipe-SQL plans

qfs --version

The long form is the field-debug anchor — semver + the git sha + the target triple it was built for (RFD §9):

$ qfs --version
qfs 0.0.2
commit:  <git-sha>
target:  x86_64-unknown-linux-gnu
wasm32:  false

Documentation

The reference docs under docs/ are generated from the binary's own registries (run cargo run -p xtask -- gen-docs) so they can never drift from the code: