CLI Tools

rill-exec

Execute a rill script file with arguments.

rill-exec <script.rill> [args...]
rill-exec -                         # Read from stdin
rill-exec --help
rill-exec --version

Arguments

Positional arguments pass to the script as a string list in $ (pipe value).

rill-exec greet.rill alice bob
# Inside script: $ == ["alice", "bob"]

Stdin

Use - to read a script from standard input:

echo 'log("hello")' | rill-exec -

Frontmatter Modules

Scripts with use: frontmatter load modules before execution:

use:
  - utils: ./lib/utils.rill

$utils.helper("input")

Exit Codes

Return ValueExit Code
true or non-empty string0
false or empty string1
[0, "message"]0 (prints message)
[1, "message"]1 (prints message)

rill-eval

Evaluate a single rill expression. No file context or module loading.

rill-eval <expression>
rill-eval --help
rill-eval --version

Examples

rill-eval '"hello".len'
# 5

rill-eval '5 + 3'
# 8

rill-eval '[1, 2, 3] -> map |x|($x * 2)'
# [2, 4, 6]

rill-check

Static analysis tool that validates rill scripts against lint rules.

rill-check [options] <file>

Options

FlagDescription
--fixApply automatic fixes to the source file
--format textHuman-readable output (default)
--format jsonMachine-readable JSON output
--verboseInclude rule category in JSON output
-h, --helpShow help
-v, --versionShow version

Exit Codes

CodeMeaning
0No issues found
1Diagnostics reported (or argument error)
2File not found or unreadable
3Parse error in source file

Output Formats

Text (default): one line per diagnostic.

script.rill:5:3: warning: message (RULE_CODE)

JSON: structured output with summary.

{
  "file": "script.rill",
  "errors": [
    {
      "location": { "line": 5, "column": 3, "offset": 42 },
      "severity": "warning",
      "code": "RULE_CODE",
      "message": "description"
    }
  ],
  "summary": { "total": 1, "errors": 0, "warnings": 1, "info": 0 }
}

Configuration

Place a .rill-check.json file in the project root to configure rules:

{
  "rules": {
    "NAMING_SNAKE_CASE": "on",
    "SPACING_OPERATOR": "off",
    "COMPLEX_CONDITION": "warn"
  },
  "severity": {
    "AVOID_REASSIGNMENT": "error"
  }
}

Rule states: "on" (enabled), "off" (disabled), "warn" (downgrade to warning).

Lint Rules

CodeCategoryDefaultDescription
NAMING_SNAKE_CASEnamingerrorVariable names must use snake_case
AVOID_REASSIGNMENTanti-patternswarningAvoid reassigning captured variables
COMPLEX_CONDITIONanti-patternsinfoCondition expression is complex
LOOP_OUTER_CAPTUREanti-patternswarningLoop body captures to outer variable
USE_EMPTY_METHODstringswarningUse .empty instead of .len == 0
UNNECESSARY_ASSERTIONtypesinfoType assertion on a literal value
VALIDATE_EXTERNALtypesinfoExternal data lacks type validation
CAPTURE_INLINE_CHAINflowinfoCapture breaks a pipe chain
CAPTURE_BEFORE_BRANCHflowinfoCapture value before branching
LOOP_ACCUMULATORloopsinfoUse accumulator $@ pattern
PREFER_DO_WHILEloopsinfoConsider do-while for init-then-loop
USE_EACHloopsinfoUse each instead of while loop
BREAK_IN_PARALLELcollectionserrorbreak inside map or filter
PREFER_MAPcollectionsinfoUse map when body has no side effects
FOLD_INTERMEDIATEScollectionsinfofold discards intermediate results
FILTER_NEGATIONcollectionswarningNegated filter condition
METHOD_SHORTHANDcollectionsinfoUse method reference shorthand
USE_DEFAULT_OPERATORconditionalsinfoUse ?? instead of conditional
CONDITION_TYPEconditionalswarningCondition not boolean
CLOSURE_BARE_DOLLARclosureswarningStored closure uses bare $
CLOSURE_BRACESclosuresinfoMulti-statement closure needs braces
CLOSURE_LATE_BINDINGclosureswarningClosure captures late-bound variable
SPACING_OPERATORformattinginfoOperators need surrounding spaces
SPACING_BRACESformattinginfoBraces need inner spacing
SPACING_BRACKETSformattinginfoBrackets need consistent spacing
SPACING_CLOSUREformattinginfoClosure params need spacing
INDENT_CONTINUATIONformattinginfoContinuation line indentation
IMPLICIT_DOLLAR_METHODformattinginfoPrefer implicit $ for methods
IMPLICIT_DOLLAR_FUNCTIONformattinginfoPrefer implicit $ for functions
IMPLICIT_DOLLAR_CLOSUREformattinginfoPrefer implicit $ for closures
THROWAWAY_CAPTUREformattinginfoCaptured variable never used

See Also