CLI
One binary, rangka. Install it with npm (npm i -D @rangka-os/cli@next, or npx @rangka-os/cli@next; only pre-releases exist so far, under the next tag), download it from GitHub Releases, run the ghcr.io/rangka-os/rangka:<version> image, or build it from rangka-os/kernel (make build). Release binaries carry the web app, Console, design system, canvas and theme/layout/print templates inside; a source build reads them from the workspace.
rangka validate --apps <dir> [--site <dir>] [--modules <dir>] [--connectors <dir>] [--json] [app ...]
rangka migrate --apps <dir> [--site <dir>] [--modules <dir>] [--connectors <dir>] --db <url> [--dry-run]
[--allow-destructive] [--rollback n] [--files-dir <dir>]
rangka backup --db <url> [--apps <dir>] [--modules <dir>] [--site <dir>] [--connectors <dir>] [--out <file>] [--org <id>] [--files-dir <dir>]
rangka restore <file> --db <url> [--into <dir>] [--files <dir>]
rangka seed --apps <dir> [--site <dir>] --db <url> [--fixtures <dir>] [--org kopi-senja]
[--email <owner>] [--password <p>] [--user-record USR-001]
rangka serve --apps <dir> [--site <dir>] --db <url> [--addr :8080] [--org <id>] [--web <dir>] [--templates <dir>]
[--modules <dir>] [--connectors <dir>] [--files-dir <dir>]
[--deploy-target dev|docker|helm|desktop|cloud|partner] [--dev-open]
[--ai-url <url>] [--ai-callback-url <url>]
rangka user add <email> --org <org> --role <role> [--outlets a,b] [--name <full name>] [--record <USR-…>]
[--reset-password] [--create-org] [--allow-linked] [--db <url>]
rangka user remove <email> --org <org> [--db <url>]
rangka numbering set <org> <series> <next> [--period 2026|2026-11] [--apps <dir>] [--site <dir>] [--db <url>]
rangka plan show|set <plan>|clear [--by <who>] [--note "..."] [--json] [--apps <dir>] [--site <dir>] [--db <url>]
rangka catalogue [--json] [--apps <dir>] [--site <dir>] [--modules <dir>] [--connectors <dir>]
rangka skills list|install|pack|check [--to <dir> | --harness claude|agents] [--out <file.zip>] [--apps <dir>] [dir ...]
rangka keygen
rangka secrets rewrap (--new-key-file <file> | --new-vault-key <name>) [--db <url>]
rangka versionEvery command that reads metadata also takes --schemas <dir> to validate against schema files on disk instead of the ones built into the binary. rangka help prints a short usage.
| Command | Does |
|---|---|
validate | Loads every .rk, checks syntax, schema and meaning, prints file:line:col level code path message, exits 1 on errors. Output is byte-identical to tools/rangka_validate.py. |
migrate | Compiles models (with overlays) into Postgres DDL: a table per model, child tables, indexes on links, docstatus and unique fields. Idempotent and diff-based. --dry-run prints each statement with its risk and changes nothing. --rollback n undoes the last n migrations. Destructive steps need --allow-destructive. See Migrations. |
backup | Writes one verified tar.gz: every table, site/, apps/, modules/, connectors/ and the uploads directory, with checksums. See Backup and restore. |
restore | Rebuilds an archive into an empty database and verifies it against the archive's checksums. |
seed | Creates the organisation (--org, $RANGKA_ORG, else the site folder name), loads fixtures/*.rk (--fixtures, $RANGKA_FIXTURES, else fixtures next to the apps directory), and the owner account (--email/--password, $RANGKA_OWNER_EMAIL/$RANGKA_OWNER_PASSWORD; demo default ceo@saga.co.id / rangka-demo) linked to the user record --user-record (default USR-001). |
serve | REST, SSE, queue workers, scheduler, Rangka ID, change sets and MCP on one port; migrates first; serves rangka-os/web at / (/app/, /console/; / redirects to /app/). Refuses metadata with errors. --dev-open makes anonymous requests act as the org owner, for local demos only. --ai-url turns on the assistant relay to a rangka-ai sidecar. |
user add | Creates a Rangka ID account and sets its role in an organisation (one role per member), so people can sign in to /app/. The email is the first argument (or --email). The password comes from $RANGKA_USER_PASSWORD (or --password, which lands in shell history) and is needed only for a new account or with --reset-password; an existing account keeps its password otherwise. --db and --org default to $DATABASE_URL and $RANGKA_ORG. An unknown organisation is refused unless --create-org is given; --record links the member to a core user record; --outlets a,b sets the outlets the member works at (--outlets "" clears them). An existing account that is linked to upstream sign-in and has no membership in the organisation is refused unless --allow-linked is given: whoever holds that upstream identity would enter the organisation as this person. Missing flags exit 2. |
user remove | Ends a membership. Exits 1 with <email> is not a member of <org> when it is not one. |
plan show / plan set / plan clear | The tenant's plan (contract 0028). show prints the plan, usage against its limits (ok, near from 80%, full, over) and what is read-only. set <plan> is an operator's upgrade or downgrade to a plan of features.rk (kept in rk_plan_changes with --by and --note); a downgrade deletes nothing, the newest outlets and people past a lower limit become read-only. clear goes back to config.rk plan. A running kernel picks the change up within 10 seconds. user add refuses a new person past the users limit. |
catalogue | Every app, module and connector with its state for the site (installed, available, not_in_plan); for each app the installed modules it shares and the ones it adds; whether connectors run. Without --site nothing counts as installed. --json is what agents read (contract 0035). |
keygen / secrets rewrap | keygen prints a new key-encryption key (base64 of 32 bytes) for RANGKA_MASTER_KEY, which the db secrets driver needs (contract 0017). Keep it out of the database and out of backups. secrets rewrap re-wraps every org's data key under a new key without touching the values: the key in --new-key-file, or the Vault transit key named by --new-vault-key (the key stays in Vault; needs VAULT_ADDR and VAULT_TOKEN). The current key comes from RANGKA_MASTER_KEY, RANGKA_MASTER_KEY_VAULT or RANGKA_MASTER_KEY_FILE. Start the kernel with the new key afterwards (RANGKA_MASTER_KEY_VAULT=<name> for a transit key). |
skills list / install / pack / check | The skills for AI agents. list shows them; install copies them into .claude/skills/ (or --harness agents, or --to <dir>); pack --out writes the release zip and refuses a failing skill; check [dir ...] lints skill folders. |
numbering set | Once at go-live, makes <next> the number a series issues next for an org, so Rangka continues the client's own numbering. It applies to the current period in the site timezone, or to --period (2026 for a yearly series, 2026-11 for a monthly one). It exits 1 instead of lowering a counter, reissuing an existing number or going below the series start, and prints the next number. Missing arguments exit 2. See Number series. |
Migrations
rangka migrate compares the models with the database and applies only the difference, in one transaction. Every step records its reverse.
--dry-runprints each statement asSQL; -- low|medium|highand a summary line with the highest risk. It runs nothing, even on an empty database.- Destructive steps are retyping a column to a type that is not wider, soft-deleting a column or table the model no longer has, and dropping a soft-deleted column or table older than 30 days. A plan that contains a retype is refused as a whole (exit 1, nothing applied) unless you pass
--allow-destructive. Columns and tables removed from a model stay in the database and show up as notes. - Soft delete renames the column or table to
_del_<YYYYMMDD>_<name>(63 bytes at most), and its indexes the same way, so a column or table that comes back gets fresh indexes (a returningunique: truefield is unique again). Rolling it back renames both back. It is dropped for good only after 30 days and only with--allow-destructive. - New columns are filled for existing records, in the same transaction, after every step: a field with a
computegets its computed value for every record and child row (submitted documents included), and a field with adefault(and no compute) gets the default where the column is empty. Only the new fields are computed, from the stored values. Expressions that read the clock, the person or company settings (today(),now(),user.,org.,tax.) are left empty, and so are, on submitted and cancelled documents, computes that read another record (a link's field,parent.,status): that record may have changed since the document was submitted. If the filled values break aunique: truefield, the migration fails, lists the records that clash, and applies nothing; fix them with the old metadata, then migrate again.--dry-rundoes not compute the values. --rollback nundoes the last n migrations (n of at least 1). A rollback whose reverse drops a column or table is destructive too and needs--allow-destructive. It supports--dry-run.servemigrates at start-up and refuses to start on a destructive retype, with a message that points torangka migrate --allow-destructive.- Change sets never apply destructive DDL. Validate and preview report such a step as an error that names
rangka migrate --allow-destructive; an operator runs it.
Backup and restore
rangka backup --db <url> --apps <dir> --site <dir> [--out rangka-all-20261103-020000.tar.gz] [--org <id>] [--files-dir <dir>]
rangka restore rangka-all-20261103-020000.tar.gz --db <url-of-an-empty-database> [--into restore-dir] [--files <dir>]- The archive holds a manifest (kernel version, row counts, SHA-256 per table and per file), every table in schema
publicasCOPYtext,site/(withoutdata/andbackups/),apps/,modules/andconnectors/(the directories the loader reads:--modules/$RANGKA_MODULES, defaultmodulesnext to--apps;--connectors/$RANGKA_CONNECTORS) and the uploads directory. A modules or connectors directory that does not exist is skipped and listed in the manifest'sabsent; a missing--appsdirectory is an error. - Connector secrets of the
dbdriver are in the archive as ciphertext and wrapped data keys only. The manifest'skek_idsnames the key-encryption key they need;backupandrestoreprint it. KeepRANGKA_MASTER_KEYapart from the archives: with another key the kernel starts but cannot decrypt them until the right key is back. - Backup is written in Go through the database connection (
COPY ... TO STDOUT), so the single binary needs no Postgres client tools. All tables are read from one snapshot. The file is written as<out>.partialand renamed when complete. Every archive (also the pre-migrate ones) is created with mode0600: it holds password, token and session hashes and the OIDC signing key. --orgarchives one organisation: rows with thatorg_id, its members' users, and only its own area of the uploads directory (files/<org>/). Tables without an org link are left out and listed in the manifest'sexcludedfield, exceptrk_meta_filesandrk_migrations. Today that isrk_keys, so a restored org archive makes a fresh OIDC signing key on first use (OIDC clients fetch the new JWKS). Rows of the installation itself (org_idempty) are left out as well, so schedule whole-database backups for disaster recovery. Without--orgthe whole database is archived.--files-dir(--filesalso works for backup and restore) resolves likeserve:$RANGKA_FILES_DIR, elsefiles.pathofsystem.rk, else./data/files. Relative paths are relative to the working directory; setRANGKA_FILES_DIRin deployments. A symlinked file inside the tree is copied as its content; a symlinked directory inside the tree is an error that names it.- Backup fails when an attachment row in scope (
rk_attachments) has no blob in the uploads directory, also when the directory does not exist. Run it whereserveruns or point--files-dir/RANGKA_FILES_DIRat the same directory. restoreneeds an empty database. It migrates from the archivedapps/,modules/,connectors/andsite/only (never the host's), adds archived columns the models no longer have, loads the tables in foreign-key order withCOPY ... FROM STDIN, resets sequences, then recomputes the checksums and compares them with the manifest. It also checks that every restored attachment row has its blob. It writes the archived metadata directories into--into(default./restore-<archive name>) and the uploads into--files(directories0750, files0640, like the files store).- An archive written by a newer kernel than the running binary is refused. A corrupt archive (bad checksum, unsafe entry, unexpected column type) is refused before anything is written.
- If a restore fails after the migration step, the schema is left behind. Retry into a fresh database.
- CI runs seed, backup, restore and a comparison of every table's checksums on each push (
.github/workflows/kernel.yml).
Production mode
Set RANGKA_ENV=production on a live installation. Then rangka migrate, rangka migrate --rollback, the migration that serve runs at start-up and every change-set apply first write a whole-database backup:
<RANGKA_BACKUP_DIR, default <site>/backups>/rangka-all-<YYYYMMDD-HHMMSS>-pre-migrate.tar.gzWithout --site the default is ./backups in the working directory. The backup archives the uploads directory that serve uses: pass rangka migrate the same --files-dir (or RANGKA_FILES_DIR) as serve, or the backup fails when attachments exist.
The backup is taken only when there is something to apply, before the first statement. If it fails, the migration does not run. Archives are never overwritten and never deleted by the kernel: clear old ones yourself, and copy them off the machine. --dry-run takes no backup.
Scheduled backups (a backup: key in system.rk) are not built yet. Until then run rangka backup from cron or a systemd timer.
Permissions
Model permissions: are enforced in REST, MCP, SSE, print, attachments and the flows people start. Actions are the schema keys: read, create, write, delete, submit, cancel, amend, export, import, print, customize.
An actor is allowed an action on a model when any of these holds:
- It is the kernel itself (seed, scheduled flows, automations, queue workers acting for the kernel).
- It has the role
owner. - The model has no
permissions:list (models not yet annotated behave as before). - An entry whose
roleis one of the actor's roles has<action>: trueand, when it hasif:, the CEL expression istrueon the record. A CEL error counts as false. Grants from several roles are added together.
With a record, if: runs on the stored record (read, write, delete, submit, cancel, amend, print) or on the new record after defaults (create). write is checked on the stored record and on the record after the patch. Without a record (a list, an SSE subscription, meta) a conditional grant counts as "maybe": lists drop the rows whose if: is false and do not count them in total, and SSE checks each event's record.
A denied single record answers 403, not 404. See REST API. API tokens, MCP and Omilo carry the member's roles and are checked exactly like a person. Child models use their parent's permissions.
Settings from the environment
Every command reads a .env file in the current directory first (variables already set win), so a project made by npm create @rangka-os needs no flags:
| Variable | Flag |
|---|---|
DATABASE_URL | --db |
RANGKA_APPS, RANGKA_SITE, RANGKA_MODULES, RANGKA_CONNECTORS, RANGKA_FIXTURES | --apps, --site, --modules, --connectors, --fixtures (validate too) |
RANGKA_ORG | --org (seed, serve, user) |
RANGKA_DEPLOY_TARGET | --deploy-target (shown in /system/status) |
RANGKA_FILES_DIR | --files-dir (serve, migrate, backup), --files (restore) |
RANGKA_ENV | production turns on the backup before migrations |
RANGKA_BACKUP_DIR | where those backups go (default <site>/backups) |
RANGKA_ADDR | --addr |
RANGKA_OWNER_EMAIL, RANGKA_OWNER_PASSWORD | --email, --password (seed) |
RANGKA_USER_PASSWORD | the password for user add (new accounts or --reset-password); --password also works but lands in shell history |
RANGKA_WEB, RANGKA_TEMPLATES | --web, --templates |
RANGKA_AI_URL, RANGKA_AI_CALLBACK_URL | --ai-url (the rangka-ai sidecar; unset turns the assistant off), --ai-callback-url (default http://127.0.0.1 + the listen port) |
RANGKA_AI_SECRET | none: sent to the sidecar as Authorization: Bearer; the same value as the sidecar's RAKA_SERVE_TOKEN |
RANGKA_MASTER_KEY, RANGKA_MASTER_KEY_FILE | none: the key-encryption key of the db secrets driver (base64 of 32 bytes, from rangka keygen), or a file that holds it. Unset: the kernel starts and refuses to store secrets |
RANGKA_MASTER_KEY_VAULT | none: the name of a Vault transit key that wraps the db driver's data keys instead (the key stays in Vault) |
VAULT_ADDR, VAULT_TOKEN, VAULT_NAMESPACE | none: the Vault server of the vault secrets driver and of RANGKA_MASTER_KEY_VAULT |
RANGKA_CHROMIUM, RANGKA_PDF_CONCURRENCY | none: the browser for PDF print (off disables PDF) and how many run at once (default 2) |
Makefile shortcuts in kernel/: make build, make test (throwaway Postgres), make test-unit (no database), make vet, make validate, make compare-python, make run-demo (ADDR=:8090 for another port; APPS=, SITE= for other folders), make sync-schemas, make rename-module MODULE=….