Work on Ronja from your editor

The Ronja CLI keeps the code behind your workflows, apps and tables as files in your own editor and version control. A push of code or SQL goes to your draft; nothing goes live until you publish. The few files that apply at once say so below.

Start a folder

A folder holds one workflow, one app, or one feature’s tables. Download an existing one:

ronja wf clone <workflow ID>
ronja app clone <app ID>
ronja pipeline clone <feature ID>

Each clone makes a new folder named after the item; run the commands that follow inside it.

Or start one in the current folder; it appears in Ronja on your first push:

ronja wf init --feature <feature ID>
ronja app init --feature <feature ID>
ronja pipeline init --feature <feature ID>

Find each ID in the address of its page. A feature’s tables live in a pipeline folder, one .sql file per Derived table. Files starting with a dot, such as .env, are never sent. For a shared module, use ronja module.

Push, test and publish

Run ronja wf status to see what changed locally and in Ronja.
Run ronja wf push to send your changes to your draft.
Run ronja wf test --param month=2026-07-01 to run your draft and see the result.
Run ronja wf publish to take it live.

An app uses the same steps with ronja app, but its test has Ronja open your draft in a browser and report what it saw, failing only with --fail-on-errors. In a pipeline folder, push builds your draft of each table and reports the rows; publish rebuilds the tables that read from it.

push and publish never overwrite a change made in Ronja since your last push; they stop and say what. push --force overwrites anyway, as does publish --overwrite-remote for a workflow or pipeline; an app’s publish never does.

A feature’s tables

A pipeline folder can also describe and check its tables; ronja pipeline push --help shows each file’s format.

Table and column descriptions

Start a .sql file with -- @table and -- @column comment lines; they are published with the table. For a table the folder does not build, use tables/<name>.json, named after the table’s entry under dependencies in ronja.json (or its ID, which works only in that organization). It writes the live table at once, so needs an Admin. Both appear in the data dictionary.

Metrics

Keep each metric’s definition in metrics/<name>.json, pushed and published like a table. A tags list applies its tags as soon as you push.

Rename a table, a metric or a file

A table or metric keeps the name it has in Ronja unless its file declares one. To rename it from the folder, add a -- @name Sales orders line to its .sql file, on the line after -- @table if there is one, or a "name" to its metrics/<name>.json file. The next push renames the same table, with its data and everything that reads it, and publish makes the name live. If someone renamed it in Ronja since your last push, the push stops and shows both names.

Renaming the file does not rename the table. To rename or delete a file, say so in ronja.json in the same commit: "moved": [{"from": "orders.sql", "to": "sales_orders.sql"}] keeps the same table under the new file, and needs a "formatVersion" of at least 5; "removed": ["old.sql"] stops the folder managing a table without deleting it. Without an entry, a renamed file gets a new table beside the old one. In a folder that does not keep its records in Ronja, commit ronja.lock.json after a push that renames something.

Health checks

Keep a table’s health checks in checks/<name>.json, named after its .sql file. They apply to the published table at once, or on publish while the table has a draft. Removing one from the file does not remove it: the push stops, and --prune silences it.

Automations

ronja automation keeps a feature’s automations as one .json file each:

ronja automation init --feature <feature ID>
ronja automation status
ronja automation push

An automation has no draft: a push changes the live automation at once, so check status first. In a shared feature, that needs an Admin or its maintainer. A folder holds only its own automations: the ones it created, or imported with ronja import feature. Deleting a file stops the next push until you restore it or pass --prune, which moves the automation to the trash for 30 days. To keep the automation running and stop managing it, list the file under "removed" in ronja.json; when you rename the file, list it under "moved". Both need a "formatVersion" of at least 5.

Deploy to more than one organization

One folder can deploy to several organizations, each a named stack such as dev or prod.

In your code, refer to tables and secrets by names you choose, such as {{ ref('orders') }}, and list each under dependencies in the folder’s ronja.json.
Run ronja bind, which offers the row of that kind with that name in this organization, ignoring case (and, when nothing matches, ignoring _, -, . and spaces). Then, signed in to production, run ronja bind --stack prod --feature <feature ID>.
Run ronja wf push --stack prod.

Check and deploy a whole repository

ronja sync status reports which folders differ from Ronja.
ronja sync check reports references that no longer resolve, such as a renamed table.
ronja sync apply --stack prod pushes and publishes every folder, creating nothing new unless you add --allow-create. It needs a sign-in that can publish each folder: it never sends anything for review.

Each exits 0 when all is well, 1 when something needs attention and 2 when it could not tell, so a CI job can stop on anything but 0. When apply exits 2, look in Ronja before running it again. In CI, these need a Full access token or one with the Admin scope (scripts and CI).

To let Ronja keep each folder’s record of what it deployed, so a build server needs nothing committed by hand, or to start a repository from a whole feature, see Deploy from a repository.