RUNNING

The rl command line

rl is a client of the same API the console uses: the console, the API and the command line are one path, so what one of them can do, the others can. There is no public download yet. A release carries it as bin/rl, beside the capabilities/ directory it reads.

Verbs

Update 2026-10-19: via_json is not only a machine credential’s. The rl audit export row above says an entry carries via_json when a machine credential wrote it. Since this date an entry for a change to a pipeline draft that a person made with an API token carries it too (credential_kind token and credential_id, the token’s id; the person is still the actor), and so a window of the log that holds one is written as file version 2 and is refused to a client that does not say it reads version 2, as rl does. The sentence above is left as it was written.

Environment variables

• RL_SERVER — the control plane URL. -server overrides it.
• RL_TOKEN — the API token. There is deliberately no flag: a token on the command line ends up in shell history. When it is unset, the token rl login kept in the OS keychain for the profile in effect is used; RL_TOKEN always wins over it.
• RL_PRINCIPAL — in CI, with no stored secret: the id of a service principal (as rl principal list prints it). rl gets the job’s identity token, trades it at the control plane for a token of that principal that lives 15 minutes, and keeps it in memory only: it is not written to disk, not put in the environment and not printed, and no command shows it. Setting RL_TOKEN as well is refused (exit 2), so a job that holds a stored token never switches identity silently. Needs RL_ORG and a CI identity token: on GitHub Actions the job’s permissions: id-token: write, which lets rl ask the runner for one; on GitLab an id_tokens entry named RL_OIDC_TOKEN, with the audience runninglake:org:<your organisation id>. A refused exchange exits 2: the principal’s CI trust tab in the console lists the refusals the control plane could verify. A GitHub identity token can be exchanged once, so the outcome is kept for the life of the process. Renewing before the token expires is not built, and no verb waits yet.
• RL_ORG — your organisation’s id, which RL_PRINCIPAL needs: the identity token is made for that organisation. (The audience cannot be looked up first, because looking it up takes a credential.)
• RL_AUDIENCE — the audience to ask the runner for, when it is not runninglake:org:<RL_ORG>.
• RL_OIDC_TOKEN — on GitLab, the job’s identity token, read by RL_PRINCIPAL.
• RL_CAPABILITIES_DIR — where the constraint bundle is. See the lookup order below.
• RL_PROFILE — which profile to read server, project and environment from. See Profiles.
• RL_CONFIG — the profiles file, when it is not ~/.runninglake/config.

Profiles

A profile is a control plane, a project and an environment under a name, so a command does not repeat -server, -project and -env on every line. They live in ~/.runninglake/config (or the file RL_CONFIG names):

[profile default]
server  = https://swim.runninglake.com
project = analytics
env     = dev

[profile prod]
server  = https://swim.runninglake.com
project = analytics
env     = prod

RL_PROFILE=prod rl status reads prod; with RL_PROFILE unset, [profile default] is read when there is one. A flag always wins, then RL_SERVER, then the profile, so a command that names everything means what it always meant. rl query list -env is the one exception: an empty -env there means every environment, and a profile does not narrow it.

A profile holds no credential, and a token line is refused (without echoing it). A token at rest lives in the OS keychain, put there by rl login under the profile’s name, and nowhere else; RL_TOKEN wins over it, which is how CI passes one. A line the file cannot be read as — an unknown key, a section that is not [profile <name>], a profile named twice — is an error that names the file and the line, and RL_PROFILE naming a profile the file does not hold is an error too: a deploy aimed at prod must never quietly go wherever the flags defaulted. Only the verbs that talk to a control plane read the file, so a broken one never stops rl schema or rl version, or the offline rl diff (the preview form, rl diff -project, does talk to one).

The variable is not a flag because rl plane preflight -profile already names an AWS profile.

The constraint bundle

rl diff and rl plan run the authoring gate against a constraint bundle, the same versioned rules the control plane pins per project. The bundle is a runtime input, not an embedded asset, and it is found in this order:

1. -capabilities dir
2. $RL_CAPABILITIES_DIR
3. capabilities/ under the project directory (-C)
4. capabilities/ in the current directory
5. capabilities/ beside the binary’s directory — the release layout ships bin/rl and capabilities/ side by side

An explicit location (1 or 2) that holds no bundle is an error, never a fall-through to a different bundle than the one asked for. When none is found, the offline rl diff cannot run (exit 2), the preview form notes it and goes on, and rl plan sends the plan with a note that the control plane runs the gate against the project’s pinned bundle.

What the gate cannot know offline

The project’s environment list. An overlay for an environment the project does not have (overlays/pord/) passes rl diff and is refused by rl plan and by hydration; the rl diff summary names every environment it projected so the typo is on the screen.

The files the control plane holds. The directory is a working copy, and a file added in the console is not in your checkout, so a sqlFile that names a well-formed path absent from the directory passes rl diff and is refused by rl plan when neither the branch nor the request holds the file (rule pipeline-file-missing; see Sending a pipeline’s files below). What the path alone proves, or a file that is here proves, is refused before anything is sent, once the tree declares a layer. The gate that rl plan and rl deploy run is the same gate and knows no more than rl diff does; the word that a file is missing is the control plane’s, in the diff of rl plan, rl deploy and rl diff -project. rl pipeline files lists what the control plane holds for a person to read. rl plan, rl deploy and rl diff -project read the same list to leave out of the request the files it already holds (see Sending a pipeline’s files), and neither gate reads it, so a path absent from the directory is still not judged missing.

Sending a pipeline’s files

A pipeline can keep files beside its pipeline.yaml, in its own folder: SQL under models/, Python under python/, Scala under scala/ and any text under files/. rl plan, rl deploy and rl diff -project send them with the declaration, in the same change set, so the SQL an asset names reaches the control plane together with the asset.

• What is sent. The working directory as it is on disk, not only the files git tracks: each file of a pipeline’s folder that the control plane would take and does not already hold, exactly as written, in path order (the next point says how rl knows). Before the request rl lists them on stderr, files to send (N), M unchanged and not sent: and then one line <path> (<bytes> bytes) for each, up to 20, then and K more. The M unchanged and not sent part is there when rl read the control plane’s list of at least one pipeline’s folder, and counts the files of those pipelines that it left out; when it read none, the line is files to send (N):. With nothing to send and files left out, the line stands alone and ends without a colon: files to send (0), 4 unchanged and not sent. It lists nothing for -no-files or when there is nothing to send, and never a file’s text. A path is printed with every control character written out (\x0a, \x1b), so a file name cannot forge a line or move the terminal.
• Only the files that differ are sent. For each pipeline the environment already holds, rl first reads the list that rl pipeline files prints (it needs the permission to read pipelines), and leaves out of the request each file the list names with the SHA-256 of the very bytes rl read. A folder of 40 files with 2 changes sends 2. Every doubt is a send, and sending a file the control plane already holds changes nothing: a file the list does not name, one it names with a different, missing or unusable fingerprint, every file of a pipeline whose list was not read, and every file of a pipeline the environment does not hold yet. When a list was not read rl says so, once for the pipeline, and sends all of its files: note: <pipeline>: the files the control plane holds for it were not read (<reason>), so every file of it is sent, where the reason is its folder has not been read from git yet, this control plane does not serve the call or the call failed. The control plane’s own error text is never printed, and a list that cannot be read never fails the command. The list is what the control plane last read of the branch, which may be a commit behind: a file equal to it is not sent, so a change made on the branch since that read is not put back, and a file that differs from it is sent. There is no option to send every file; changing a byte sends it. The list names the first 100 files of a folder by path, and a larger folder is cut there: rl sends the files after the last one listed whether or not they changed, and says so, note: <pipeline>: the control plane lists only the first 100 files of its folder, by path, so the K file(s) after <path> are sent whether or not they changed. rl compares the bytes it read when it started, so a file edited while rl runs is neither compared nor sent in its new form. rl plan, rl deploy and rl diff -project all do this; the offline rl diff sends nothing and reads no list.
• A file git does not track is marked. When git answers, a file in the list rl prints before it sends that is not in git’s index (one that was never added, or one an ignore rule covers) carries the mark after its size, <path> (35 bytes, not tracked by git), and the line that counts the rest says how many it holds, and 4 more, 1 not tracked by git. It is a mark and not a question: rl still sends the working directory, nothing waits for an answer, and a job in CI is never stopped by one. When git does not answer (it is not installed, the directory is not a repository, git refuses the directory or takes more than a few seconds) nothing is marked and nothing is said. A file inside a submodule is never marked: the index lists the submodule as one entry and rl does not ask git inside it. rl asks git for its index and nothing else, with the repository’s own commands switched off.
• rl plan and rl deploy send a file that differs from the control plane’s list as a replacement and can replace a console edit with an older copy. They send no fingerprint of the text a file began from, as the console’s Edit does, so a file whose text differs from the one the control plane holds is replaced, whoever changed it last. When anyone edits files in the console, bring your working copy up to date from the repository before you run rl deploy. Leaving out the files the control plane already holds makes a request smaller and never makes a replacement safer. No rl verb reads a file’s text either.
• -no-files withholds every file, the ones you changed as well, and sends the declarations only. It says so in one note: line, and only when the tree has a file it would have sent. It is a usage error (exit 2) for the offline rl diff, which sends nothing. It is no way out for a new pipeline that names a sqlFile: nothing is sent, so once the tree declares a layer the control plane holds no file for a pipeline that does not exist yet and refuses it (pipeline-file-missing). A new pipeline that names a sqlFile needs its file, or inline SQL. Wherever rl offers -no-files as the way out (the bounds below, a credential scan that could not run, an agent’s token) it says so beside the offer.
• rl does not remove a pipeline’s files. A file missing from the working directory is left where it is on the control plane. The console’s Files tab removes a file.
• What is not sent. A file the folder recognises and the control plane would refuse (a name the platform would not write, text over 256 KiB, not UTF-8 text, or empty) is named in a warning: line on stderr, with the reason and what to do about it, and the build goes on. The files the platform writes are the one exception: they are named in a note: line, never a warning (the next point). An empty file is the one that bites: python/__init__.py is empty, is not sent, and the control plane will not hold it unless it has a comment line. Files the folder does not look at (a README, notes, any other extension outside files/, a name with a backslash in it) are counted in one note: line that names the first five paths and counts the rest. Hidden files and symbolic links are skipped without a word. A folder that holds files and no pipeline.yaml gets one warning, and none of its files is sent.
• A SQL file that no asset names gets a warning: and is never refused. For a .sql file in a pipeline’s folder that rl would send and that no asset names as its sqlFile or its pythonFile, rl diff prints warning: <path>: no asset in any environment uses this file. It is kept with the pipeline. It is what the console’s Files tab calls not used, and it stops nothing: the exit code is what it was. The offline form prints it on stdout with the other findings, and its verdict reads ok, N warning(s); the preview (-project and -env) prints it on stderr and leaves the control plane’s diff alone on stdout. Which declaration it judges depends on the form. The offline rl diff knows no environment, so it reads the pipeline’s base declaration and every environment’s overlay merged over it, and warns only when none of them names the file; a file that one environment’s asset list uses is used. rl diff -project p -env e judges that environment alone and says no asset in <env> uses this file. It says nothing where it cannot tell (an overlay that does not merge, a declaration it cannot read), for a file that already has a warning of its own (empty, too big, not text, a name the platform does not write), or for a Python or Scala file, a flow or DESIGN.md. The warning has no rule: line.
• Files the platform writes are not sent. flows/<name>.yaml and DESIGN.md in a pipeline’s folder are written by the platform, and a request cannot add or change either: the control plane refuses it, in a sentence that says the platform writes the file. Removing one is allowed. rl leaves them where they are, sends neither, and names them in one note: line on stderr, note: N file(s) in pipeline folders are written by the platform and are not sent, followed by the first five paths and a count of the rest. It is a note and never a warning, the plan’s exit code is what it was without them, and they are not counted against the bounds below. A name that only looks like one of them (design.md, flows/X.yaml, flows/a.b.yaml, flows/x.yml) is not one, and is counted with the files outside the convention. A SQL file the platform generated from a flow is a model like any other, and rl sends it.
• An asset whose sqlFile names a file in the folder here that rl does not send stops the plan, before anything leaves the machine and before the gate runs, with exit 1: asset <name> names <file>, which rl cannot send (<reason>); fix the file or give the asset inline SQL, rule file-not-sent. The sqlFile judged is the one the environment being planned gets, so an overlay of that environment that points an asset at an unsent file is refused too; the offline rl diff knows no environment and judges every overlay. One that names a symbolic link gets a warning, because rl does not follow links. This is rl plan, rl deploy and rl diff -project. The offline rl diff runs the gate first and says each defect once: where the gate has its own sentence for the same asset’s sqlFile (the next point) that sentence stands and this one is dropped, so the count in its verdict is a count of defects, and where the gate has none this line stands: an empty named file, a file rl kept no bytes of (below), and every tree that declares no layer.
• A sqlFile the control plane refuses, and which verb says what. All of it is judged once the tree declares a layer, as every reference rule is: in a tree that declares none, rl says nothing about a sqlFile but what the previous point says. The rule is the control plane’s one function, run on the working copy, so it says only what a working copy can prove.
  • A well-formed path absent here passes rl diff (the control plane may hold the file) and is refused by rl plan when neither the branch nor the request holds the file: rule pipeline-file-missing, in the diff, with the pipeline, the asset and the file in its sentence. rl plan exits 0 on a refused plan; rl deploy and rl diff -project exit 1.
  • What the path alone proves is refused before anything is sent, in the control plane’s own sentence, whether or not the file is here: a path that is not a .sql file outside files/, a path with a name that begins with a dot (a path under a hidden directory is refused, not passed), a name the platform does not write (an upper-case letter), a backslash (its own sentence: which has a backslash in it; use / as the separator) and a path that leaves the folder. The offline rl diff says it and exits 1. rl plan, rl deploy and rl diff -project say it from the gate they run before sending, when a bundle is at hand and the file is not one rl itself refuses to send, and exit 1; with no bundle at hand the gate does not run, rl notes it, and the control plane says the same sentence in a refused plan. .//models/x.sql, ./models/x.sql and models//x.sql name models/x.sql and are not refused.
  • A file that is here and unusable. The offline rl diff says the control plane’s sentence for one that is not UTF-8 text (pipeline-file-unusable, which is not UTF-8 text). rl plan, rl deploy and rl diff -project stop on file-not-sent first, in rl’s sentence and its own rule id, because that line returns before the gate.
  • The size limit, exactly. A file may be 262,144 bytes (256 KiB). rl keeps the bytes of a pipeline-folder file up to 262,145 bytes and, for a larger one, only its path and its size. The offline rl diff says pipeline-file-unusable (which is over 256 KiB) for an asset that names a file over the limit, whatever its size, and adds its own warning: that the file is not sent. rl plan, rl deploy and rl diff -project say file-not-sent first, because that line returns before the gate. All exit 1.
  • -no-files sends no file, so the gate judges no folder, rl says nothing about any sqlFile, and the control plane judges every sqlFile against what it holds. The offline rl diff refuses -no-files (exit 2).
• Bounds, checked before anything is sent. One pipeline carries at most 100 files in one change, and one change set carries 100 files and 1 MiB of file text and paths together, so a pipeline new to the environment carries at most 100 in its first change, and a pipeline that exists is refused at 101 as a change set is. The count is of every file the request would carry, after the files the control plane already holds have been left out, and does not include the files the platform writes. Over a bound rl sends nothing, says the counts and offers -no-files, which withholds ALL files, the changed ones included: exit 1 for rl plan and rl deploy, exit 2 for the preview, which stores nothing. The refusal’s offer of -no-files ends (a new pipeline that names a sqlFile needs its file, or inline SQL), because a tree sent without files is judged by the control plane against the files it holds. A folder of more than 100 files or 4 MiB is refused by the control plane, which rl does not check.
• What rl prints, and where. rl adds no file text of its own. The control plane’s diff does show the text of every file that changes, rl prints that diff as it is, and so the text of a changed file lands in your terminal and your CI log. Each stream:
  • stdout: for rl plan and rl deploy, the control plane’s diff, rules fired, the change set line and the sqlFile refusal, as before. For rl diff -project, the control plane’s diff and nothing else.
  • stderr, for all three verbs and only when the tree has files: the warning: lines, the outside-the-convention note, the CRLF note, the -no-files note, the files to send list, the line files in this change set: 2 added, 1 replaced, 4 unchanged (from what the control plane accepted; it says nothing has been applied), and what follows a refusal. A tree with no pipeline-folder files prints the same bytes on both streams as before.
  • When the plan is refused, rl prints on stderr each reason that carries a file and line, because the diff names no file for a credential and the control plane gives the file and line to the change set’s author alone; a reason with no path is already in the diff and is not printed again, and neither is a warning. A refusal for a sqlFile names the pipeline, the asset and the file in its own sentence, so it reads the same in the diff, in a log and in the console. That sentence is said once on a terminal. The diff carries it under its BLOCKED <rule> line, so for a refused plan rl prints on stderr only where it is, <path>:<line>: where the BLOCKED <rule> finding in the diff is; under -o json of the preview the diff is a field of a document and has not been read, so the finding is then said in full.
• A string that looks like a credential in any file sent, changed or not, refuses the whole plan. The way out is an entry in the config repository’s .runninglake/secret-allowlist.yaml. rl does not read that directory, so its plan key does not move when the entry does; the control plane stores the refusal under the key and, now plans the same tree again when the key comes back (it reads the allowlist from the branch), answering with a new change set when the entry now excuses the findings and with the refusal that stands when it excuses some. A refusal whose findings are the same files and lines is still the stored one. A refused change set cannot be withdrawn. rl says: to retry after fixing an allowlist entry, run it again once the entry is on the branch: the control plane reads the allowlist there and plans the same tree again; an older control plane answers with the refusal it stored, and then a file rl sends (a pipeline.yaml or a file in a pipeline folder) must be changed first. If the control plane could not scan at all, it says so and names -no-files instead, with the caveat above (a new pipeline that names a sqlFile needs its file, or inline SQL), and the same older-control-plane clause.
• A stored refusal is replayed for the same tree, whatever its rule, except the ones the control plane judges again (a credential finding, a plan-dependent refusal, a refusal made while something could not be read). When the control plane answers a refused plan with one it stored earlier, rl says: this is the refusal stored earlier for this exact tree; changing a file rl sends or a declaration plans it again.
• A draft that already exists with the same effect is returned instead of a new one (planned earlier without files, by a colleague, or from the console). It holds no record of these files, and rl says an existing change set with the same effect was returned (<id>); it carries no record of these files and goes on: rl deploy submits it as it would any draft.
• A control plane that does not take files stores the declarations and reports none of the files back; one that reports only some is treated the same. rl plan and rl deploy both exit 1: rl says that the change set above carries declarations only and was not submitted, and prints rl withdraw <id> for it. The change set is stored as a draft, which a teammate who can approve could still submit, so rl prints the command that takes it back and does not run it; rl deploy does not submit it. The preview stores nothing and exits 2. Exit 2 means nothing was started and exit 1 means a draft exists, so a script that retries on 2 and stops on 1 does the right thing.
• A token minted for an agent is refused when the tree has files: rl prints the control plane’s sentence and says to use -no-files, and to give a new pipeline inline SQL and not a sqlFile, because an agent cannot send the file and a new pipeline that names one is refused (pipeline-file-missing) once the tree declares a layer.
• Files with CRLF line endings are sent as they are, with one note.
• The offline rl diff judges the same tree as rl plan and rl deploy: the file warnings, and the sqlFile refusal for what the working directory proves, which makes it exit 1. It judges what the working tree can prove and not what the control plane holds, so a path absent here is the control plane’s to refuse. A green rl diff of a tree whose pipelines name files is therefore not the control plane’s word that it holds them: rl plan against the environment is, which is why rl lake seed ends by saying to run it before pushing.

Previewing on the control plane

rl diff -project p -env e asks the control plane what the working tree would change in one environment, and prints the answer. It reads the tree and builds the change exactly as rl plan does, with the same files and the same lists and notes, but nothing is stored: no change set, no approval waiting for anyone, no entry in the audit log. A second preview of the same tree is a second render, not a replay of the first.

• stdout is the control plane’s diff, character for character, and nothing else. It is the diff the control plane renders for you as the reader: what a restricted layer hides from your credential is hidden from the preview too, and the violations that refuse the tree are in it, in the control plane’s own words. Everything rl adds — the verdict line, the notes about the constraint bundle and the engines it judged against, the rules that fired, whether the environment follows approvals — goes to stderr, so a pipe or a redirect carries the diff only.
• Only an explicit -project makes it a preview. A profile that names a project, RL_SERVER being set, or a project named anywhere else never turns a bare rl diff into a call to a control plane: the offline gate stays offline. -env, -server or -o without -project is a usage mistake, and -env is required with -project. The server and the credential come from -server, then RL_SERVER, then the profile, as for every verb that talks to a control plane.
• A missing constraint bundle is a note, not a failure. The offline form needs the bundle and exits 2 without one. The preview runs the local gate when a bundle is at hand and says when none was, and the control plane runs the gate against the project’s own bundle either way. An overlay for another environment is not part of what the preview sends, so the control plane does not judge it; the local gate, which runs when a bundle is at hand, does check every environment’s overlays and refuses the tree before anything is sent if one of them is refused.
• Exit 0 when the control plane would take the tree, 1 when it would refuse it (the reasons are in the diff, and a tree the local gate refuses is refused before anything is sent), 2 when nothing was previewed: a usage mistake, a directory with no resources in it (rl plan would plan every deletion; a preview refuses what is most likely the wrong -C), a tree that needs more than 100 changes at once (preview a part of it), a tree whose files are over what one request carries (see Sending a pipeline’s files), a control plane that does not take files (or names only some of them), no server or credential, a credential that was not accepted, a control plane that cannot be reached or is rate limiting you, or a control plane that does not serve the call yet.
• -o json prints the control plane’s response as one document on stdout and nothing else (see Output); the exit code is the same under either form.

Posting the preflight report

rl plane preflight -plane <id> prints its report as always and then posts it to the control plane, which keeps the newest one per plane. AWS only. Without -plane nothing is posted and no configuration file is read.

• The plane id is the uuid rl-controlplane register-plane printed as id, and the one the console’s Planes page shows. A blank value (an unset shell variable) is refused, not skipped.
• The control plane is -server, else RL_SERVER, else the active profile’s server: the address you sign in to the console at. It must be https (http is accepted for a loopback address only), because the token and the report go to it.
• The credential is the control plane’s, not the cloud’s: the token rl login stored, or RL_TOKEN (see Environment variables and Profiles). It must be organisation-wide: a token confined to one project is refused, because a plane belongs to the organisation, and only an owner or an admin can mint one.
• What is sent: the account and region the checks ran against, and each check’s id, status and text with ARNs, access keys and external ids taken out on your machine. The tfvars the command prints, the external id among them, are never sent. A check’s id is its name as a word (a version in the name is not part of it), so the same check has the same id from run to run.
• What happens to it: the control plane calls a report stale after 24 hours, and records whether the account the checks ran against is the one the plane records (verified is the command’s own statement compared, not proof). Today the plane’s Connect page shows that a report exists and how old it is; the check-by-check table is still being built.
• A post that fails does not change what the checks found. The report is printed first. A blocked report is still exit 1 and says it was not posted (or may not have been, when the control plane did not answer); a clean one whose post failed is exit 2. The plane id, the address and the credential are checked before any check runs.

Exit codes

rl diff and rl plane preflight document three:

rl query documents four of its own, so a CI job that runs a smoke query can tell “the query failed” from “no query ran” from “the query is not over”:

rl audit export and rl audit verify use four, so a CI job that archives the audit log can tell “the chain is wrong” from “the check did not happen”. rl audit delivery status, test and attempts use the same four; what each means for them is in the paragraph after the table:

rl audit delivery status and rl audit delivery attempts exit 0 when the read happened, whatever the state of delivery or the outcomes listed, 2 on a usage mistake or a credential the server did not accept, and 3 when the read did not happen (the control plane could not be reached, refused the credential’s role, or does not serve audit delivery). rl audit delivery test exits 0 when every check that ran passed, 1 when a check failed (the class is printed) or the control plane refused the plane, 2 on a usage mistake or when -plane must be chosen, and 3 when no check ran or the answer did not agree with itself. A 3 is never a pass.

rl query get and rl query list exit 0 when the read happened, whatever the status of the queries they show, 2 on the usage and not-wired cases above, 4 when -download was given and the fetch failed, and 1 otherwise.

rl query logs -list exits 0 when the list was read, 1 when the job has no readable log or the caller may not read it, and 2 on a usage mistake, a missing server or credential, Not built yet and Not on this control plane; it never exits 3 or 4, because it fetches no segment. Reading a stream’s lines or downloading it adds 4: the fetch from the plane failed even with a fresh link, or a segment was not one rl can read. It never exits 3.

rl query cancel exits 0 when the control plane recorded the request or the query had already ended (read it back with rl query get to know it is over), 2 on the usage and not-wired cases above or when the control plane answered with no record at all, and 1 otherwise: the cancel was refused, the query was not found, the request could not be handed to the data plane and nothing was recorded, or the control plane answered a query that had not ended with no request on it.

rl gates documents three, by whether anything was decided:

rl ai policy documents three, by whether the policy was read:

rl routing rules and rl routing rule exit 0 when the read happened, whatever state the rules are in. They exit 1 when the control plane answered no in its own sentence (it has no rule of that id, or the credential may not read routing), and 2 when nothing was read: a usage mistake (a stray argument, a missing or extra id), no server or credential, a credential that was not accepted, or a control plane that does not serve the call.

rl plan and rl deploy exit 2, as rl diff does, for a constraint bundle the loader refuses: the bundle is the invocation’s fault and not the tree’s, and nothing was sent. A tree the bundle refuses is still 1.

rl plan and rl deploy exit 1 against a control plane that does not take files, or names only some of the files they sent: the control plane stored a draft of the declarations, so there is something to take back. The change set is named and the command that withdraws it is printed, not run. rl diff -project exits 2 in the same case, because a preview stores nothing.

rl storage-rule list, rl storage-rule get and rl storage-rule events exit 0 when the read happened, whatever state the rules they show are in. They exit 2 when nothing was decided: a usage mistake (an unknown -state, a -place that is not a place, a rule name with a slash in it), no server or credential, a credential the server did not accept, a control plane that does not serve storage rules or answers Unimplemented or FailedPrecondition, and a call this build of the control plane has not built yet, whose own sentence is printed. They exit 1 when the control plane answered and the answer was no: a rule that is not there (or that this credential cannot see, which the control plane words the same), or a credential that may not read.

rl addon list exits 0 when the read happened, whatever state the add-ons it shows are in. rl addon get exits 0 only when the add-on is ready, and 1 for every other state, after printing the answer. Both exit 1 when the control plane answered and the answer was no: an environment that is not there (or that this credential cannot see, which is worded the same), an environment bound to no data plane, a kind with no row, or a credential that may not read the plane’s add-ons. They exit 2 when nothing was decided: a usage mistake (no project or environment, none in the profile, a flag after the kind), no server or credential, a credential the server did not accept, and a control plane that does not serve the call.

rl source list, rl source get, rl source kinds and rl source prereqs exit 0 when the read happened, whatever state the sources they show are in. They exit 1 when the control plane answered and the answer was no, in its own sentence: a source that is not there (or that this credential cannot see, which it words the same), a credential that may not read configuration (config.read), a -type or -state it refuses by name, and, for prereqs, a draft it cannot write steps for (no database user, no tables, a name it cannot write safely) or an environment on the shared trial plane, where no source can be prepared for; and when the answer was read and could not be written to standard output (a closed pipe), which is said. They exit 2 when nothing was decided: a usage mistake (a stray argument, an empty -type, -state or -f, both a name and -f or neither, -sql with -o json, a -flavour that is not one of the four, a name that is not a source’s, -env with no -project), a -f file that cannot be read, is over 1 MiB or is not a Source the gate accepts (nothing is sent), no server or credential, a credential the server did not accept, a control plane that cannot be reached, answers a fault, does not serve the call or has not built it (its own sentence is printed), and one that redirects the request (a redirect is never followed). rl source drop-slot makes no call and exits 2 every time, with a sentence on standard error; a name that is not a source’s, or a flag, is refused before it.

rl code-step list exits 0 when the read happened, an environment with no code step included (it says so, on stdout under text and on stderr under -o json). It exits 1 when the control plane answered and the answer was no (a refusal, an environment that is not there) and 2 when nothing was decided: a usage mistake (a stray argument, a missing or malformed -project or -env, an unknown -o), no server or credential, a call this control plane does not serve, a failed call, or a listing that did not end within 200 pages.

rl pipeline files exits 0 when the read happened, whatever the folder holds: a folder with problems, a listing cut short at 100 files, a folder with no files, and a folder the control plane has not read from git yet, which it says on stderr and does not print as empty. It exits 1 when the control plane answered and the answer was no: a pipeline that is not declared in that environment (or that this credential cannot see, which is one sentence for both) or a credential that may not read pipelines, in the control plane’s own sentence. It exits 2 when nothing was decided: a usage mistake (no project or environment and none in the profile, a name that is not a pipeline’s, a flag after the name), no server or credential, a credential the server did not accept, a control plane that cannot be reached or does not serve the call (it says so, and that nothing was attempted). Nothing is printed to stdout when a read fails, and the credential is taken out of what is printed.

rl pipeline params exits as rl pipeline files does. It exits 0 when the read happened, whatever the declaration holds: a table, none, and a declaration the control plane could not read, which it says on stderr and does not print as none. It exits 1 when the control plane answered and the answer was no: a pipeline that is not declared in that environment (or that this credential cannot see, which is one sentence for both) or a credential that may not read pipelines, in the control plane’s own sentence. It exits 2 when nothing was decided: a usage mistake (no project or environment and none in the profile, a name that is not a pipeline’s, a flag after the name), no server or credential, a credential the server did not accept, a control plane that cannot be reached or does not serve the call. Nothing is printed to stdout when a read fails, and the credential is taken out of what is printed.

rl storage-rule test exits by the verdict and by nothing else, so a script can branch on it:

rl asset list, rl asset get and rl asset coverage exit 0 when the read happened. They exit 1 when the control plane answered and the answer was no, in its own sentence: an asset that is not there (or that this credential cannot see, which the control plane words the same), a credential that may not read (catalog.read), or a -kind, -tier or -q it refuses by name. They exit 2 when nothing was decided: a usage mistake (a stray argument, an empty -kind, -layer, -tier or -q, a name that is not an asset or has a slash it should not, -env with no -project), no server or credential, a credential the server did not accept, a control plane that cannot be reached, answers a fault, does not serve the call or has not built it (its own sentence is printed), and a control plane that keeps handing back the same page token. Nothing is printed to stdout when a read fails, and the credential is taken out of what is printed.

rl lineage and rl lineage impact exit 0 when the read happened, an answer the control plane cut at its limit included. They exit 1 when the control plane answered and the answer was no, in its own sentence: an asset that is not there (or that this credential cannot see, which it words the same), a credential that may not read lineage (lineage.read), an environment whose lineage the control plane has not worked out (a change held for review, or briefly an environment that existed before lineage was recorded), which it refuses in its own sentence and never answers with an empty graph, or a -depth over its limit or a -direction it refuses, by name. They exit 2 when nothing was decided: a usage mistake (not exactly one asset, a -direction that is not up, down or both, a -depth below 1 or not a whole number, a flag given and empty, a name that is not an asset or has a slash it should not, -env with no -project, a -depth given to impact), no server or credential, a credential the server did not accept, a control plane that cannot be reached, answers a fault, or does not serve the call or has not built it (its own sentence is printed), and an answer that lists an edge whose end it does not list, which is refused whole. Nothing is printed to stdout when a read fails, and the credential is taken out of what is printed.

rl steward domain list, rl steward assignment list, rl steward queue, rl steward certification list, rl glossary list, rl glossary get and rl glossary export exit 0 when the read happened, 1 when the control plane answered and the answer was no in its own sentence (a credential that may not read, a list it refuses to give without a narrowing, an asset it words as not there), and 2 when nothing was decided, as rl asset list does; a listing that fails on any page prints nothing.

rl steward domain create, update, archive and restore, rl steward assignment set, rl asset certify, rl asset decertify and the five rl glossary writes (propose, update, approve, reject and deprecate) use the same three. domain create, rl asset certify and the five rl glossary writes have a key the control plane keeps; domain update, archive, restore, assignment set and rl asset decertify do not:

rl withdraw, rl approve, rl reject, rl env rename and the preview form of rl diff use three, by whether the control plane answered:

rl migrate analyse, rl migrate analyses, rl migrate analysis (also with -csv) and rl migrate delete use three, by whether the control plane answered and what it said. This is the contract these verbs start with, and it is a recommendation that can still change.

rl secret list, rl secret get, rl secret reads, rl key list and rl key get exit 0 when the read happened, whatever state the references or keys they show are in. They exit 1 when the control plane answered and the answer was no, in its own sentence: a reference or a key that is not there, a credential that may not read (the permission is named), or a window that ends before it starts. They exit 2 when nothing was decided: a usage mistake (a stray argument, a missing -project or -env where both are needed, a reference’s name, a project or an environment outside the control plane’s grammar (1 to 63 lowercase letters, digits, - and _), an ARN, an alias or anything else that is not a key’s id where a key’s id goes, a -since or -until that is not a time, a flag given and empty; a refusal of this kind does not repeat what was typed, and nothing is sent), no server or credential, a credential the server did not accept, a control plane that cannot be reached, answers a fault, or does not serve the call or has not built it (its own sentence is printed), a list that keeps handing back the same page token, and a list the control plane refuses as a whole. The shared trial plane offers no secrets and has no key of its own, so its list prints nothing and exits 2: an empty list under exit 0 would say that none is declared. Nothing is printed to stdout when a read fails, and the credential is taken out of what is printed. rl secret set exits 2 on every input and makes no call.

rl principal list, get, disable, credential list and credential revoke exit 0 when the call was made and done. They exit 1 when the control plane answered and the answer was no, in its own sentence (no such principal or secret for this credential, a credential that may not, with the permission named). They exit 2 when nothing was decided: a usage mistake (a stray argument, a missing -project or -reason, a project outside the control plane’s grammar, an id that is not a UUID, a -state that is not active, disabled or inert; a refusal of this kind does not repeat what was typed, and nothing is sent), no server or credential, a credential the server did not accept, a control plane that cannot be reached, or one that does not serve or has not built the call. rl principal create, update, enable, delete and rl principal credential create, rotate exit 2 on every input and make no call. Nothing is printed to stdout when a call fails, and the credential is taken out of what is printed.

rl trust list and rl trust delete exit as the principal verbs do. rl trust evaluate exits by what it found, and by nothing else: 0 when the policy matches the claims, 1 when it does not (the claim-by-claim result is printed first), 2 when nothing was evaluated (a usage mistake, a claims file that is not one JSON object, a refusal of the call). rl trust create exits 2 on every input and makes no call.

rl webhook list, deliveries and disable exit as the principal verbs do: 0 when the call was made and done, 1 when the control plane answered and the answer was no (in its own sentence, with the permission named), 2 when nothing was decided (a usage mistake: a stray argument, a missing -project, a pipeline, trigger or environment that is not one name, an id that is not a UUID, an -outcome it does not know, a negative -since; a refusal of this kind does not repeat what was typed, and nothing is sent; no server or credential; a credential the server did not accept; a control plane that cannot be reached or does not serve the call; a list that keeps handing back the same page token). rl webhook preview exits by what it found, and by nothing else: 0 when the body maps cleanly, 1 when parameters would be refused, 2 when nothing was previewed (a usage mistake, a body that is empty or larger than 256 KiB, a refusal of the call). rl webhook create and rotate exit 2 on every input and make no call.

rl secret check exits by what the check found, and by nothing else, so a script can branch on it. A check has two answers about the reference and one that says nothing about it:

The only word that is a 0 is Found. A script that retries on 3 is safe, and one that is told “it will not be found” by a word nobody here has read is not, so an outcome this rl does not know is a 3 and never a 0 or a 1. A check on a plane that cannot check yet prints that word and exits 3: it never prints a version or says that the secret was read.

rl key check exits by what the check found, and by nothing else, so a script can tell a key that is not usable from a check that could not be made:

rl run exits by what became of the run, and by nothing else, so a script can branch on it:

The line a script reads, run <id>: <status>, is on stdout whatever the exit; the sentence that explains a 1, 2 or 3, the key line and the notice of a replay are on stderr.

Every other verb exits 1 on any error.

A command rl does not know exits 2, not 1 — rl dif is a usage mistake, and a CI script must not read it as “the tree was refused”. It returned 1 until 2026-09-21. rl run exits 2 for the same reason when nothing was started. rl with no arguments prints the usage text to stderr and exits 2; rl help prints it to stdout and exits 0.

What rl query prints, and what it does not

The record of the run, as the control plane holds it: status, the engine together with the reason the record stores for it (duckdb — pinned: no other engine serves the SQL window), a rule row beneath it, and the figures the plane measured in human units (1.5 GiB, 0.41 s).

The rule row says only what the code decided. rule none consulted means the record names how the engine was chosen and no rule from the constraint bundle was consulted (the table format is not known when the engine is chosen for a window query, so today this is every new record). rule not recorded is a record written before the control plane kept the kind of reason. A rule id, when a record carries one, is printed as it is. A kind this rl does not know (a newer control plane’s) gets no rule row, because the row would claim something rl cannot read, and a record with no engine yet gets none either: rl query get prints engine not chosen yet — The record names no engine yet. and rl query list prints not chosen yet in the ENGINE column. A statement the control plane had to keep waiting, because the plane’s SQL engine was already running as many statements as it takes at once, carries one more row: waiting for a free slot on the plane's engine, since <time> while it is in line, waited <duration> for a free slot on the plane's engine once it was sent, and waited for a free slot on the plane's engine, and ended before one came free when it was cancelled or gave up first. The status stays queued while it waits, and a statement that never waited has no such row. Streamed engine <engine> — <reason> lines are unchanged. On a failure, the error CLASS — a token such as plane_not_connected — with the one sentence that says what it means (the plane did not take the query in time); a token rl does not know is printed with “the message stays in the plane”, because an engine’s error text routinely embeds row values and never transits the control plane. No rows, for the same reason. This is exactly what the console’s SQL workspace shows, from the same three calls, with the same sentence for the same class.

What it says about cost, and what it never computes. A finished query’s record carries charged, the vCPU-seconds the query used: a quantity against your compute allowance, never a price, and not settled until the plane’s final report has been counted, never a zero. Beneath it, once the control plane has priced the query, is the price row: a figure at the node’s list rate, with the formula, the rate and what it leaves out in the same line (a cold start and the idle tail are not attributed yet), or not priced: and the reason (no rate card, a node the plane did not report, a spot node with no list rate). A query on a shared engine has no list price, so it reads not priced and a metered line gives its usage at the engine’s own cluster rate, an estimate the bill supersedes. When a reconciliation has read your cloud bill for the node-hours the query ran on, a reconciled row gives the bill’s own figure (its usage and its share of the nodes’ idle, in the bill’s currency, and whether every hour was in) and a difference row sets it against the list price, usage only, and says why there is none when the two are in different currencies or there is no list price. A figure whose bill line named no currency is withheld, not printed in a guess. Every one of these is read from the record: rl never computes a price from CPU seconds, and a row the control plane did not send is absent, never 0.

Two figures are withheld rather than printed as zero. A succeeded record with the class report_lost is a query the plane finished whose report never reached the control plane; it prints report report_lost — succeeded on the plane; the numbers were not received and no figures, and exits 0, because nothing failed. And bytes scanned prints not reported when the plane sent zero, because the runner cannot measure it yet and a zero in that row would read as a measurement.

Output

Human text is not a stable interface, with one exception. What a verb prints for a person — its columns, its wording, which lines appear — changes whenever a person would be better served by the change, without notice and without a version. Do not parse it. The exception is a violation, as rl diff, rl plan and every verb that runs the gate print it (the last paragraph of this section): the file:line: it opens with — after warning: when it does not block, and file: alone when there is no line to point at — and the rule: line under it are kept stable for CI to match on. Those verbs have no -o json yet, apart from the preview form of rl diff, and a CI gate needs something to match.

-o json is the contract. It prints exactly one JSON document on stdout: the RPC’s response message as protojson, which is the JSON the Connect protocol itself carries on the wire, so its rules are protobuf’s own JSON mapping: field names in lowerCamelCase, enum values by name, 64-bit integers as strings, timestamps in RFC 3339, and a field at its zero value absent unless it tracks presence and was set (an optional scalar, a oneof member, a message), so a script reads a missing field as its zero value. The shape is therefore the API’s protobuf message, and a change that removes, renames or retypes one of its fields is refused before it is released. Whitespace is not part of the contract. Anything a verb says to a person meanwhile — progress, a warning, an empty listing’s hint — goes to stderr, so rl project list -o json | jq reads one value.

The document is the response as your rl understands it. rl decodes the answer and prints it again, so a field the control plane gained after your rl was built is absent from the document, and reads as its zero value, until you upgrade rl. Upgrade before relying on a new field.

-o takes text (the default) or json. Any other value is a usage mistake: exit 2, and nothing is sent. The exit codes are the same under either form.

That is every verb so far. A new verb is born with -o json; the others gain it later, and until then they do not accept -o.

A violation is printed as file:line: message, then the rule id a CI script can match on (rule: iceberg-dml-engines), then what to do instead (try: ...). A rejection without an alternative is a support ticket, so every rule that fires carries one.