# CLI

> Install the rodarion CLI, configure rodarion.json and .env, and sync language files with upload, download and migrate.

`rodarion` is a single Go binary for macOS, Linux and Windows (amd64 and arm64). It syncs
the language files in your repository with a Rodarion project through the REST API.

## Install

```bash
# macOS and Linux (Homebrew)
brew install cubera-ch/tap/rodarion

# Windows (Scoop)
scoop bucket add cubera-ch https://github.com/cubera-ch/scoop-bucket
scoop install rodarion
```

Native packages (`.deb`, `.rpm`, Arch `.pkg.tar.zst`) and plain archives are attached to every
[release](https://github.com/cubera-ch/rodarion-dist/releases/latest), together with a
`checksums.txt`. Check the install with `rodarion version`, which also tells you when a newer
release exists.

## Configure

Run `rodarion init` in the repository root. It writes:

- **`rodarion.json`**: where your language files live and how they are laid out. It holds no
  secret, so commit it.
- **`AGENTS.md`**: the playbook a coding agent follows to analyse the repo and import it.

A minimal `rodarion.json`:

```json
{
  "name": "default",
  "base_url": "https://app.rodarion.com/api",
  "relative_path": "./resources/lang",
  "export_profile": "json_single",
  "source_locale": "en",
  "use_locales": false,
  "auto_translate": true,
  "api_key": "${RODARION_API_KEYS.default}"
}
```

The token itself goes into a gitignored `.env` next to it. A CI secret with the same name
takes precedence.

```bash
RODARION_API_KEYS='{"default":"<your API token>"}'
```

Use a JSON array instead of a single object to sync several directories or projects in one
run. Give each block a `name` and target it with `--name <block>`.

## Everyday commands

| Command | Alias | What it does |
| --- | --- | --- |
| `rodarion upload` | `up` | Push new source keys and texts. Missing translations are machine-translated if a provider is set up. |
| `rodarion download` | `down` | Pull translations into your language files. `--min-status approved` exports only approved texts. |
| `rodarion upload-download` | `up-down` | Upload, wait for machine translation, then download. |
| `rodarion migrate-download` | `migrate-down` | First import of a project that already has translations: uploads the source, patches every local target language, fills the gaps, downloads. |
| `rodarion translate <key> <lang> <text>` | `tl` | Edit one translation. `--file edits.json` applies a batch; `--fetch` prints texts marked *update needed* as a worklist. |
| `rodarion project` | `whoami` | Show the token's project, its locales and, for a trial, the limits. |

## Setup commands

| Command | What it does |
| --- | --- |
| `rodarion init` | Scaffold `rodarion.json` and `AGENTS.md`. |
| `rodarion guide` | Print the agent playbook without writing files. |
| `rodarion profile list` / `create` | List or create export profiles (format, layout, separators, placeholder style). See [Formats](/docs/formats). |
| `rodarion providers` | List the machine translation providers. |
| `rodarion provider-setting list` / `create` | Show or add a provider with your own key. |
| `rodarion ci <platform>` | Scaffold a promote-on-merge or release workflow. See [CI](/docs/ci). |
| `rodarion promote --branch <name>` | Fold a merged branch into the central project. See [Branch workflow](/docs/branch-workflow). |
| `rodarion discard` | Drop the current branch's shadow project. |

## What the CLI protects

- **Approved translations** are never overwritten by an upload or by machine translation.
- **Existing keys** in the central project are never changed by an upload from a stale file.
  Edit those in the app or with `rodarion translate`.
- On a **trial** that could not hold the whole project, downloads go to `rodarion-trial/`
  instead of over your real files.

## Support and security

The CLI is made by Cubera Solutions AG and supported at least until 27 July 2031. Security updates ship
as new releases, so keep it current (`brew upgrade rodarion`, `scoop update rodarion`).
Report vulnerabilities to [security@cubera.ch](mailto:security@cubera.ch); our
[disclosure policy](https://www.cubera.ch/security/) explains how we handle reports.