CLI
Every ritla command and its options: init, add, diff, update, login and scan, what ritla.json holds, and the exit codes for CI.
Commands#
| Command | What it does | Useful options |
|---|---|---|
ritla init | Detects Next.js or Vite, Tailwind v4 and your alias; writes ritla.json; installs @ritla/core and imports its styles; asks how your app switches to dark mode and which fonts to use; installs the theme tokens when a key is set. To change the folders, edit ritla.json by hand: there is no folder flag yet. | --css <path>, --dark class|data-theme|system, --font ritla|app, --strict, --skip-theme, --force, --no-install |
ritla add <item...> | Adds components and their dependencies: files, npm packages, styles. | --overwrite, --dry-run, --no-install, --own-theme (with style-strict only) |
ritla diff [item...] | Compares your items with the registry, as a unified diff. | --check (exit 1 when an update is available) |
ritla update [item...] | Takes registry changes into files you have not edited, and adds any registry item your items now depend on. | --force, --dry-run |
ritla login | Where the license key goes, and a check of the setup. | |
ritla scan --project <id> | Runs a Ritla scan and fails on findings at or above a severity. For CI. | --fail-on critical|high|medium|low|never, --timeout, --json |
Every command takes --cwd <path> and --help.
Every component reads the theme, so install it before the first one: npx ritla init with your license key set, or npx ritla add style. Skip it and the components land as unstyled markup, with no error.
Existing apps and strict mode#
The theme adds its names beside Tailwind's defaults and changes none of your classes, so init, add and update install into an existing app as they do into a new one. A @theme block of your own keeps working beside it, unless it defines one of the theme's exact names (Tokens).
ritla init --strict, or ritla add style-strict later, adds the opt-in strict stylesheet. It removes Tailwind's default scales and adds the theme's base styles: the font family, no letter spacing in Arabic, the focus ring, and the theme's duration and easing on a bare transition. Use it only in a new app or a dedicated layout. If your stylesheet has its own @theme, ritla add style-strict stops with exit code 1 and writes nothing, because strict mode would replace that theme; pass --own-theme to let it, or leave strict mode out. ritla init --strict counts as that consent. See Strict mode.
ritla.json#
init writes ritla.json, and you commit it. It holds your aliases, the folders they map to, your stylesheet, your dark-mode and font answers (dark, font), and a hash of each file add wrote, which is how diff and update tell a registry change from your own edit. It never holds a key.
ritla scan in CI#
ritla scan reads a scan API key (create one in your dashboard, Settings) from RITLA_API_KEY. This is a different secret from the license key.
npx ritla scan --project <id> --fail-on high| Exit code | Meaning |
|---|---|
0 | Passed. |
1 | Findings at or above the threshold. |
2 | A usage or setup error. |
3 | The scan could not run: refused, failed or timed out. |
A timeout is a failure, never a pass.
On GitHub, the scan action runs the same scan as a workflow step.