Tools
| command | what |
|---|---|
rowstile init [--schema app] [--users app.users] [--role app_user] [--out db] | a first policy drafted from your tables and foreign keys, a test file, rowstile.toml, and a note for coding agents in AGENTS.md (see below); --role names the app role the app connects as (without it: the one role the tables are granted to, else app_user; run it after the migrations that make the tables and the role) , --out the folder for the policy and its test, below the current one (rowstile.toml is written in the current folder; when one is there already, here or in a folder above, init uses it, and says so when it names another policy than the draft) |
rowstile dev [p.authz] [--once] [--no-studio] [--studio-port 4983] | on every save of the policy or its tests: check, show who gains and loses access (for a permission gained, the rules that read it), push, test, write the clients; a mistake stops it before applying. With [migrations], it writes the migration once you stop editing. Studio runs beside it, and can write, as with rowstile studio --write (--no-studio: not; on a port another program holds, dev says so and goes on without it) |
rowstile studio [--port 4983] [--write] | Studio, a local web page: the app's tables as anyone, a type at a time, in its key's order (the rows they can't see greyed; a masked column they may not read shown empty, marked masked, as they get it), why they hold a permission or not and what would grant it, the policy as a graph, the policy file's access diff on this data, shares and pending requests, and a test from "Ann should see this". The grid shows a table's first eight columns, and any masked column after them, and names the others. It counts a table's rows, and the rows the person sees, up to 10,000: past that it says more than 10,000. Read-only unless --write (then shares and decisions are made as the person you view as, and what why and the access diff try is rolled back whole); it listens on 127.0.0.1 only, and the address it prints carries a token A token it doesn't take, one from an earlier start of Studio say (each start makes a new one), is answered 401 with words that say so and which address to open A change's body is 64 KB at most: a longer one is refused before it is read (413), as any change is when Studio is read-only (403), and one that hasn't come whole after 10 seconds is given up on (408) Each request connects again: a database it can't reach, or loses while a request waits, is said as the command says it, with 503 A share link is turned off with authz.revoke_link: Studio refuses to unshare one, and shows no Unshare button for it The graph tab loads Mermaid from jsDelivr, a pinned version checked against its hash: without the internet the page shows the graph as text, for any Mermaid viewer |
rowstile why --as user:42 folder 7 edit | yes and why; or no, why not, and the smallest changes to the data that would grant it: each is tried in a savepoint and undone, and comes with every other permission it would give them, on any object, who else would gain this one on the folder, and what the people in what it replaces (the owner a column names now) or in a group a deny reads would lose, on any object . It offers only changes that change something, and a share only as authz.share would make it: its shared if judged as someone who may share the object , one of the first 20 of them; a note says when there are more . It counts up to 1,000 objects of a type for each person: past that, a permission is said as not counted, not as a number |
rowstile migrate [p.authz] [--name N] [--check] [--tool T] [--dir D] [--one-phase] [--downgrade] | the policy's changes since the lock file, as a migration for your tool (no database needed); --check exits 1 when a change has no migration (for CI); --tool and --dir stand in for [migrations]'s tool and dir; --one-phase and --downgrade: see Migrations |
rowstile push [p.authz] [--development] [--downgrade] | a development database brought to the policy by the same migration (never production); --development marks a database that already has a policy as one, once A development database you built by running the migrations (to try them) has a policy and no mark: push and rowstile dev say so (AZ610) until rowstile push --development marks it. Push reads those conditions again too, and refuses one on a dropped column in the same words, whatever the change. |
rowstile review [p.authz] [--base main] [--markdown|--json|--annotations] [--out FILE] [--db DSN] | what the change since --base does: meaning, access (on a review database), risk, tests, deploy; the pull request comment with --markdown, or in a file with --out FILE, beside what it prints |
rowstile fmt [--check] [files] | writes policies and test files one way; --check exits 1 when one isn't (for CI) |
rowstile apply [p.authz] [--force] [--downgrade] | apply it whole, with the files it includes (read from disk by the command), unless it is in force already (the same text and build, and what it made still there: row-level security on, its policies and triggers). A condition only a function reads (a signing-in type's where, a shared ... if) that no longer runs, on a column the app dropped since, is refused with its line, as when it was first applied (AZ613), not taken as unchanged. --force applies in any case and computes every inheritance table again, which a plain apply keeps: what to run when authz.verify() says false |
rowstile check p.authz | only report its first mistake (in the policy's own test lines too), as file: line N: message [AZ201]; exit 1 if there is one |
rowstile help AZ201, rowstile --version | what a mistake's code means, and the same mistake fixed (error codes; help errors lists them); the version, and the Python it runs on |
rowstile prove [p.authz] [--worlds N] | every invariant in many small worlds, with no database: the smallest counterexample (exit 1), or that none was found. A data check (authz.check_invariants()) says the data keeps it; prove says whether the policy does --worlds N (400) is how many worlds it draws at random. It also tries, at each size, the corners (each condition true on every row, or on none) and the worlds a draw rarely makes (dense links, a chain one link longer than the policy reads), so the count it says is more than N. |
rowstile test --coverage | the tests, then the branches of each permission no passing check makes true, with their lines (rowstile dev shows how many on each save). The checks that count are the can ones (user 1 can view folder 3): a cannot, or a statement run as someone, covers nothing |
rowstile snapshot [--check] [--out FILE] | who holds what on this database's data, one sorted line per object and permission (in access.snapshot beside the policy, or where [review] snapshot or --out says): on review data, commit it, and a pull request that changes access changes it; --check exits 1 when it is out of date |
rowstile indexes [--check] | the lookups the policy makes into the app's tables that no index serves (a type's key among them: each check on one object finds its row by it), why, and the line to add for your migration tool (rowstile doesn't add indexes to your tables: your ORM's diff would see them); dev warns at start. For goose and dbmate, which run each migration in a transaction where Postgres builds no index concurrently, the line says to put its CREATE INDEX CONCURRENTLY in a migration of its own that starts with -- +goose NO TRANSACTION or -- migrate:up transaction:false. A partitioned table's line has no CONCURRENTLY, which Postgres refuses there. A CREATE INDEX CONCURRENTLY that fails leaves an unfinished index under the name the line gives, so running the line again fails ("already exists"): rowstile indexes names that index first, to drop: for goose and dbmate, in a migration of its own too. Prisma's and Drizzle's line names the columns: where a model's fields map them under other names (ownerId for owner_id), write the fields. |
rowstile plans [--as user:1], rowstile bench [--people 10] [--rounds 20] | each governed table read as someone, timed, with full scans of other tables and per-row subplans named (a partition's scan is the read itself ); p50 and p95 of reads, lists, checks and updates (undone) as people in the data: --people of them (10), --rounds times each (20). An update it times is of a row the person may update |
rowstile diff p.authz [--users 1,2] [--limit 200] | who gains and loses what (see Governance), the first 200 changes listed, or as many as --limit says; changes nothing It makes the new policy in a transaction it undoes, so the app's tables stay locked while it asks, and it waits for a command changing the policy, as apply does. Run it on a copy or a staging database, not on production at its busiest. |
rowstile lint | what authz.lint() finds, the worst first; exit 1 on an error or a warning |
rowstile jwks [URL] [--check] | stores the keys an identity provider signs its tokens with, as it serves them at URL (its JWKS), in place of the stored ones: authz.login_jwt checks RS256 tokens with them (Identity). Each key is added, replaced, kept, removed, or skipped with the reason. Run it again when the provider's keys change, from a scheduled job or a deploy step: a key the provider retired is removed, and its tokens sign nobody in from then on. The set is fetched over https, from the server the URL names (a redirect to another server is not followed), 64 KB at most, within ten seconds. An answer that is no key set stores nothing (exit 2), and neither does a set with no RSA key for signatures (AZ719, exit 1): the stored keys stay. --check stores nothing and exits 1 if storing would change the keys, for a monitor. Without a URL it lists the stored keys: each one's kid, size and day. |
rowstile test [tests.authz ...] | the current policy's tests, these named tests, and the invariants; exit 1 if any fails |
rowstile can|explain|perms|list --as user:42 ..., rowstile who [--as user:42] ... | ask the database as someone |
rowstile explain-rule --as user:42 app.files insert --row '{...}' | why a write is (or would be) refused |
rowstile sql --as user:42 "SELECT ..." | a statement as the app role, signed in as someone; rolled back. A statement that returns no rows says what it did in the server's words: UPDATE 0, as user:42; rolled back is a write the rules let change nothing |
rowstile lsp | the language server: errors while typing, hover, go to definition, references, outline, completion (of tables and columns too, with database in rowstile.toml: not --db, DATABASE_URL or the PG* variables, which only fill in what its string leaves out, but the password: the string's, or PGPASSWORD in .env beside rowstile.toml, never the editor's own, since the folder opened names the host ; a database it can't reach yet is tried again some seconds later ). It reads rowstile.toml again when it changes; a mistake in it is shown on it, and the policy is checked without it until it is fixed |
rowstile mcp | the MCP server, for coding agents (see below) |
rowstile graph [p.authz], rowstile client py|ts|ts-sdk|go|csharp|ruby|rbs|java|rust|elixir|php|electric|zero|powersync [p.authz] | diagram and typed helpers (ts: a client for pg; ts-sdk: the policy's names alone, for an app on the TypeScript SDK, what [clients] ts writes in such an app; ruby: the policy's names as constants, for the Ruby SDK; rbs: their signatures, for Steep; java: the policy's names, as the class [clients] java's path names, src/main/java/com/example/AuthzNames.java for com.example.AuthzNames; rust: the policy's names, a module for the Rust SDK; elixir: the policy's names, as the module [clients] elixir's path names, lib/my_app/authz.ex for MyApp.Authz; php: an enum of each type's permissions in the namespace Authz, for the PHP SDK, one file for Composer's autoload files; electric: each synced table's shape, for the app's route in front of Electric, a preview: Electric; zero: the sync index's tables and each synced table's filter, for a Zero schema and its query endpoint, a preview: Zero; powersync: PowerSync's streams of the mirrored tables, a preview: PowerSync): of the file, else of the policy rowstile.toml names, else of the policy in force; with --db, of the policy in force on that database, and --db beside a file is refused . powersync reads each mirror's columns from the database where the policy is applied (--db, or rowstile.toml's database), so it refuses a file: of rowstile.toml's policy, it reads the database rowstile.toml names . With no language, rowstile client writes the files [clients] names, and says of each that it wrote it or that it was up to date |
rowstile reapply [--force], rowstile remove --yes [--downgrade] | the policy in force again, after an upgrade (--force: and every inheritance table computed again); to take the policy out |
editor/ | the VS Code and Zed extensions: highlighting (SQL inside { } too) and the language server; a Tree-sitter grammar for Helix and Neovim; other editors start rowstile lsp themselves |
rowstile <command> --help prints that command's own lines, and rowstile --help all of them, on stdout. A command refuses an option it doesn't take, another command's too, with exit 2, rather than ignore it: rowstile check --db URL says that check reads no database. The exit code is for scripts and CI: 0 when the command did what was asked and found nothing wrong; 1 when it found something or something was refused (a mistake in the policy, a failing test, a lint warning, a --check that finds a difference, a counterexample, an error from the database); 2 when it couldn't do what was asked (a mistake on the command line or in rowstile.toml, a file it can't read or write, a database it can't reach or lost); 130 when stopped with Ctrl-C. rowstile dev and rowstile studio run until you stop them: Ctrl-C is how they end, with 0 (dev --once, which stops by itself, with 130). rowstile review exits 0 whatever it finds: test and migrate --check are the gates.
Commands without a policy file read rowstile.toml, found in the current folder or a folder above it:
policy = "db/policy.authz"
tests = ["db/tests/*.authz"]
database = "env:DATABASE_URL" # a DSN or URL, or env:NAME
[clients]
py = "backend/app/authz_client.py" # written by rowstile dev (and rowstile client) on every change
ts = "frontend/src/authz.ts"
go = "internal/authz/authz.go" # the policy's names, for the Go SDK
csharp = "Api/Authz.g.cs" # the policy's names, for the .NET SDK
ruby = "app/lib/authz.rb" # the policy's names, for the Ruby SDK
rbs = "sig/authz.rbs" # ... and their signatures, for Steep
java = "src/main/java/com/example/AuthzNames.java" # the policy's names, for the Java SDK
rust = "src/authz.rs" # the policy's names, for the Rust SDK
elixir = "lib/my_app/authz.ex" # the policy's names, for the Elixir SDK (MyApp.Authz)
php = "database/authz.php" # the policy's names, for the PHP SDK
electric = "src/shapes.gen.ts" # the synced tables' shapes, for a route in front of Electric
zero = "src/zero.gen.ts" # the sync index's tables and filters, for a Zero schema
powersync = "powersync/sync-config.yaml" # PowerSync's streams of the mirrored tables (reads the database)
[migrations]
tool = "alembic" # alembic, prisma, drizzle, efcore, rails, ecto, laravel, sql, goose, dbmate,
# flyway, django or sqlx
dir = "alembic/versions" # where the tool keeps them (each tool has a default)
lock = "db/policy.lock" # what the migrations made so far (default: next to the policy)
write_after = 300 # rowstile dev writes the migration this long after the last save
# (seconds; 0: never, run rowstile migrate yourself)
[review]
snapshot = "db/access.snapshot" # rowstile snapshot's file (default: access.snapshot next to the policy)The paths in it are from its own folder, wherever the command runs, and so is migrate --dir; --out (of init, review and snapshot) is from the current folder.
The database is --db (before or after the command), else rowstile.toml's, else DATABASE_URL, else libpq's PG* variables (PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE, PGOPTIONS, PGSSLMODE, PGSSLROOTCERT, PGCHANNELBINDING, and the others libpq reads; not a password file or a service file). DATABASE_URL, those nine PG* variables, and the one database = "env:NAME" names, may be in .env.local or .env beside rowstile.toml (in the current folder while there is none), where Next.js, Prisma and many others keep them: the environment comes first, then .env.local, then .env, and rowstile dev says when the database came from a file. Nothing else in those files is read, a file that is a link out of the folder isn't read at all, and with --db neither is: the command line named the database. Values are as dotenv writes them: quotes, # comments, export, and ${NAME} filled in. A URL's ?sslmode=, ?host=, ?port= and the like are read, and ?ssl=true as sslmode=require, as libpq reads it (where the URL has both, the one written last wins); any other value of ssl is refused. A URL's parameters that libpq doesn't have are left to the ORM they are for (?schema=, ?pgbouncer=), but one a letter away from one of libpq's (?sslmod=, ?SSL_MODE=) is refused, as a typo. Each of libpq's settings, in a connection string, a URL or a PG* variable, is done as libpq does it, left alone where that changes neither what is checked nor where the command connects (application_name, keepalives, sslsni and the like), or refused, naming it: a service, a password file where no password is given, a host address apart from its name (hostaddr), several hosts, client certificates, GSS encryption, OAuth. Three things differ from libpq. The command reads no password file (~/.pgpass): give the password in the connection string or PGPASSWORD. Where connect_timeout isn't given, it waits 10 seconds for the server (libpq waits as long as it takes; connect_timeout=0 does here too). And the command sends no client certificate: libpq sends ~/.postgresql/postgresql.crt to a server that asks for one. A value in a string of keywords is quoted as for libpq (password='it\'s'). In a URL, a #, a ? or a [ in the password is the password's, as libpq reads it, but a / there must be written %2F. A message about the connection string never repeats a piece of the password, one that wasn't quoted or escaped too. Where nothing names them, the defaults are libpq's: the system's user, a database named after it, and the server's socket in /var/run/postgresql (Debian's and Ubuntu's folder) or /tmp (libpq's own, as Homebrew and Postgres.app build it), whichever has it, or localhost on Windows. The warnings the server sends are printed on stderr, as psql prints them, those it sends as the session starts too (a collation version that doesn't match the system's, a setting of the database's it can't take). When the server ends the session in the middle of a command (pg_terminate_backend, a server shutting down), the command says it lost the database and why, in the server's words (lost the database: terminating connection due to administrator command), exit 2.
TLS is used when the server has it and required with sslmode=require. The server's certificate is checked against a root certificate: the one sslrootcert names, else root.crt in libpq's folder (~/.postgresql, or %APPDATA%\postgresql on Windows), with require too when there is one, as libpq does; verify-ca and verify-full don't go on without one. sslrootcert=system checks it against the system's roots and checks its name, as verify-full, and a weaker sslmode with it is refused. A certificate sslcrl, sslcrldir or root.crl lists as revoked is refused. Over TLS the password exchange is bound to the server's certificate when the server offers it (channel_binding=prefer, the default, as in libpq; disable never does), so a connection string from Neon's dashboard works as it is. With channel_binding=require, a server that asks for the password any other way, or signs the command in without asking, is refused before anything is sent to it. require_auth says which ways the server may ask, and target_session_attrs which session will do, as in libpq.
The files rowstile.toml names to be read (the policy, the tests, the lock) are in its folder or below. Those it names to be written (the snapshot, the clients, the migrations' folder) are in the git repository it is in (the first folder up from its own that holds a .git), so a monorepo's ../frontend/src/authz.ts works, or in its folder when it is in none. A path out of them, or a link out of them, is refused and named. A setting it doesn't know, or one of the wrong type, is an error. Getting started goes through all of it; the cookbook has tested patterns and troubleshooting what people run into.
Your stack, step by step: stacks (each stack an SDK serves, from FastAPI and Next.js to Rails, Spring, Go, Rust, Phoenix, Laravel and ASP.NET Core; the sync engines Electric, Zero and PowerSync; and the SQL any other language sends). To try rowstile with nothing installed, the playground runs the compiler and a real Postgres in the browser (Pyodide and PGlite).
Coding agents: AGENTS.md
rowstile init leaves a note for the coding agents that work in the app, in AGENTS.md at the project's root: where the policy and its tests are (those rowstile.toml names), the loop after an edit (check, push on the development database, test, or dev), that production takes migrations, that the app connects as the app role and signs each transaction in, and where the rest is (llms.txt). Without it an agent sees a route with no permission check and adds one.
The note sits between <!-- rowstile:begin --> and <!-- rowstile:end -->. An AGENTS.md that is there keeps its text and gets the section at its end; one that has the markers is left as it is, so the section is yours to edit, and init run again changes nothing. Delete the section if you don't want it.
Coding agents: rowstile mcp
rowstile mcp is a Model Context Protocol server (stdin and stdout) with the command's own tools: check, prove, review, test, why, lint, and push to a development database. Each call runs the command once, in the folder the agent started it in, so rowstile.toml names the policy and the database. check also returns the mistake's file and line. A finding (a mistake, a failing test, a counterexample) is an answer with ok: false; a call that couldn't run (no policy file, no database) is an error. So is a call with arguments the tool refuses (one missing, or one that reads as an option): the error is in the tool's answer (isError), with the reason, so the agent sees it and can correct the call. The server reads the agent's messages while a call runs: a ping is answered at once. A call the agent cancels (notifications/cancelled) gets no answer, and its command is stopped as Ctrl-C stops it: a cancelled push keeps nothing. Stopped (SIGTERM, as an agent's client stops it), the server first stops the commands its calls run, the same way, and waits for them: none keeps running after it. An agent is given the command to start it, in its own settings for MCP servers:
{"command": "rowstile", "args": ["mcp"]}Each release publishes the server's entry to the official MCP registry, as io.github.rowstile/rowstile, for clients that find servers there. The entry names the npm package, which brings its own Python.
push is the only tool that changes anything, and it is marked so; production takes migrations.