> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools and CI

> Format, check and test an RSL project with rslc, on your machine and in a continuous integration job.

`rslc` is one program with a command for each job. [Install Relativities](https://docs.canary.effectiveai.app/relativities/setup.md) to get it.

| Job | Command | Passes when |
| - | - | - |
| Format a file | `rslc fmt FILE` | Always; it rewrites the file in the one canonical layout |
| Check the format | `rslc fmt --check FILE` | The file already has that layout |
| Check a program | `rslc check FILE` | Every check holds |
| Run a worked example | `rslc eval SCENARIO` | Each expected value equals the computed one |
| Explain a message | `rslc explain E-CODE` | The code exists |
| Read the reference | `rslc docs`, `rslc examples` | Always |
| Package a rater | `rslc export FILE --format bundle --out OUT.zip` | The check passes |

[Use the rslc commands](https://docs.canary.effectiveai.app/rsl/commands.md) shows each command on a rater, and [the command reference](https://docs.canary.effectiveai.app/rsl/reference/commands.md) lists every option.

## Lay out a project

Keep one program in one folder. The examples on this page use the `auto` example:

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc examples get auto --out auto
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
WROTE auto/enums/Territory.csv
WROTE auto/rater.rsl
WROTE auto/scenario.rsl
WROTE auto/tables/BaseRate.csv
WROTE auto/tables/DeductibleFactor.csv
WROTE auto/tables/DriverClass.csv
WROTE auto/tables/LimitFactor.csv
WROTE auto/tables/MileageFactor.csv
WROTE auto/tables/TerritoryByZip.csv
WROTE auto/tables/ValueFactor.csv
```

| File | Holds |
| - | - |
| `rater.rsl` | The program |
| `tables/*.csv` | One file for each rate table, named after the table |
| `enums/*.csv` | One file for each enumeration that the program reads from data |
| `scenario.rsl` | A worked example with its expected values |

Commit all of them. The bundle that `rslc export` writes is a build product.

## Format

RSL has one layout, and `rslc fmt` writes it. A team that formats on save has diffs that show only real changes.

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc fmt --check auto/rater.rsl
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
PASS auto/rater.rsl is formatted
```

## Check and test

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc check auto/rater.rsl
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
PASS auto/rater.rsl (strict)
cost premium: 27 + 7*|Policy.drivers| + 25*|Policy.vehicles| (each list of size 1: 59, 3: 123, 10: 347)
```

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc eval auto/scenario.rsl
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
PASS auto/scenario.rsl (passed)
targets: {"p.premium": {"Num": {"exact": "2240", "value": 2240.0}}, "v1.mileage_factor": {"Num": {"exact": "1.048", "value": 1.048}}, "v1.rated_age": {"Num": {"exact": "19", "value": 19.0}}}
PASS assertion: assert@p
PASS assertion: assert@v1
PASS assertion: assert@p
```

The first line of each command starts with `PASS` or `FAIL`.

## Run the three commands in CI

A job that runs these three commands holds a project to its format, its checks and its worked examples:

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc fmt --check auto/rater.rsl
rslc check auto/rater.rsl
rslc eval auto/scenario.rsl
```

Each command reports its result in its exit status, so a job stops at the first failure:

| Exit status | Meaning |
| - | - |
| `0` | The command passed |
| `1` | A check failed, the format differs, an expected value differs, or a file is missing |
| `2` | The command line is wrong |

Install the same release of `rslc` in CI as on each author's machine.
[Versions](https://docs.canary.effectiveai.app/rsl/explanation/versions.md) explains which number is which.

## Read results from a program

Add `--json` before the command for one JSON value on standard output:

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc --json check auto/rater.rsl
```

The object holds `ok`, the `cost`, and each diagnostic with its `code`, `message` and `location`.

## Use the reference from an editor or an agent

The reference ships inside `rslc`, so it matches the installed compiler and works offline.

* `rslc explain E-CODE` prints why a check exists, a program that gets the message, and the fix.
* `rslc docs TOPIC` prints the sections, types, functions and annotation keys.
* `rslc examples get NAME --out FOLDER` saves a complete program that passes the check.

A coding agent that writes RSL reads these three in place of a web search.

## Related

* [Run a scenario](https://docs.canary.effectiveai.app/rsl/how-to/run-a-scenario.md) writes a scenario file.
* [Test a rater](https://docs.canary.effectiveai.app/rsl/how-to/test-a-rater.md) compares premiums with independent rating examples.
* [Check messages](https://docs.canary.effectiveai.app/rsl/reference/check-messages.md) lists every message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.