Skip to content

Use the Ronja CLI

The ronja command-line tool (CLI) lets you use Ronja from a terminal, a script or an AI coding assistant.

On a Mac, install it with Homebrew:

Terminal window
brew install ronjatech/tap/ronja

On Linux, or anywhere you have Go:

Terminal window
go install github.com/ronjatech/ronja-cli/cmd/ronja@latest

On Windows, download it. This needs no admin rights:

  1. On the latest release, download ronja_<version>_windows_amd64.zip, or ronja_<version>_windows_arm64.zip on a PC with an Arm processor.
  2. Unzip it. Create a folder of your own, for example %LOCALAPPDATA%\Programs\ronja (type it into File Explorer’s address bar to go there), and move ronja.exe into it.
  3. Search the Start menu for Edit environment variables for your account, select Path under your user variables, click Edit, then New, and paste that folder.
  4. Open a new terminal. If Claude Code or your editor is running, restart it, because it reads Path only when it starts.

On a Mac or Linux you can also download it from the releases page. Check that it works:

Terminal window
ronja --version

To have Claude Code install the CLI and sign you in instead, see Build in Ronja with Claude Code.

  1. Run ronja login. The CLI prints a short code and opens your browser.
  2. Check that the browser shows the same code, and that you recognise the machine under Requested by.
  3. Click Authorize.
  4. Run ronja whoami to see the user, organization and role the CLI acts as.

On a server without a browser, run ronja login --no-browser and open the printed link elsewhere. The code works once, for 10 minutes.

ronja query runs read-only SQL against your tables and prints the result as CSV:

Terminal window
ronja query "SELECT * FROM {{ ref('<table ID>') }} LIMIT 10"

Refer to a table by its ID, shown in the address of its page in Ronja. --file report.sql reads the SQL from a file, and --out result.csv saves the result. A failed query exits with an error.

When a table the query read has stopped updating, or is built on a table that is failing, ronja query prints a Warning: line about it, naming the table and what is failing. The line is kept out of the CSV, including a file saved with --out. The query still succeeded; the warning tells you the numbers may be out of date. See When something a table is built from is failing.

The CLI reads dates in UTC, while Ronja uses your own timezone, so daily or monthly totals can differ.

Let an AI coding assistant build with Ronja

Section titled “Let an AI coding assistant build with Ronja”

An assistant such as Claude Code or Codex builds in Ronja through the CLI, with your sign-in. For Claude Code, Build in Ronja with Claude Code walks through it step by step:

  • ronja context prints who you are, the rules Ronja follows for you — your organization policy, the policies for your own people property values and your own policy — and a guide to Ronja’s API. Have the assistant run it first. When your CLI is out of date, the API guide it prints can start by saying so and naming the update to run. The assistant runs it once; when it can’t, it tells you and carries on.
  • ronja api <path> sends an API request and attaches your token itself, so it never appears in the command or its output.
  • ronja secret create --in-browser opens a new secret’s page, where you type the key yourself, so it never passes through the assistant:
Terminal window
ronja secret create --feature <feature ID> --name Stripe --host api.stripe.com --in-browser
  • ronja propose asks you to approve a deploy instead of making it. It changes nothing in Ronja: it uploads a change list of what ronja sync apply would create and change, and you approve it in Ronja, which then deploys it as you. The assistant never deploys. See Let an AI assistant ask before it deploys and Approve a change list.

ronja sync apply remains the direct deploy, with no approval, for a build server and for you deploying by hand.

To let an assistant only read your data from the terminal, give it a token with only Data, set to Read, through RONJA_URL and RONJA_TOKEN (see Use it in scripts and CI); ronja query and ronja api work with it. To only ask questions about your data, you can also connect the assistant read-only: see Connect Claude to Ronja for Claude, or Use Ronja from your AI assistant for other assistants.

Download a workflow’s code, edit it in your own editor, and send it back:

Terminal window
ronja wf clone <workflow ID> monthly-report
cd monthly-report
# edit the code, then:
ronja wf push
ronja wf publish

A push goes to your draft until you publish; see Work on Ronja from your editor.

  • ronja db runs SQL and migrations on a managed database.
  • ronja secret new-value <secret ID> opens the form for a new value of an API key or a database login, where you type it yourself, then prints what Ronja found when she tried it. See Update or rotate credentials.
  • ronja secret connect gmail connects a service by signing you in to it. Adding any other integration from the terminal, step by step, is at /docs/api/guides/create-a-secret.md#adding-a-new-integration-end-to-end on your Ronja domain.
  • ronja api reads and changes organization settings (changing needs an Admin).
  • ronja <command> --help explains any command.

A job signs in with two environment variables: RONJA_URL, your Ronja’s address, and RONJA_TOKEN, an access token. Keep the token in your CI system’s secrets, never in your repository; in GitHub Actions:

env:
RONJA_URL: https://cloud.ronja.tech
RONJA_TOKEN: ${{ secrets.RONJA_TOKEN }}

An Admin creates tokens under Account → Access tokens; ronja token create opens that form already filled in. A job that pushes, publishes or runs ronja sync needs a Full access token, or one with the Admin scope, because the CLI first asks Ronja which organization the token is in; a token limited to other scopes works with ronja api and ronja query. ronja login --with-token stores a token as a sign-in, and needs the same kind.

With nobody at the terminal, commands never ask questions, and a failure exits with an error.

The CLI tells you, at most once a day, when a newer version exists. Install it with:

Terminal window
ronja update

If you installed with Homebrew, run brew upgrade ronja instead.

On Windows, ronja update can’t replace the running program. Download the newest zip from the latest release and replace ronja.exe with the one inside. If you installed with go install, run the same go install command again.

A sign-in from ronja login lasts 90 days (ronja whoami shows when it expires); one stored with --with-token keeps its token’s expiry.

  1. Run ronja logout to remove the sign-in from this computer.
  2. If the token may have leaked, revoke it under Account → Access tokens. Signing out does not.