# 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](/reference/migrations.md) |
| `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](/errors/index.md); `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](/reference/governance.md)), 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](/reference/identity.md)). 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](/reference/sync.md#electric); `zero`: the sync index's tables and each synced table's filter, for a Zero schema and its query endpoint, a preview: [Zero](/reference/sync.md#zero); `powersync`: PowerSync's streams of the mirrored tables, a preview: [PowerSync](/reference/sync.md#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/`](/editor.md) | 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:

```toml
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](/getting-started.md) goes through all of it; [the cookbook](/cookbook/index.md) has tested patterns and
[troubleshooting](/troubleshooting.md) what people run into.

Your stack, step by step: [stacks](/stacks/index.md) (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](https://github.com/rowstile/rowstile/blob/v0.1.0-beta.5/playground/README.md) 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](https://github.com/rowstile/rowstile/blob/v0.1.0-beta.5/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:

```json
{"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.
