CLI Commands and Exit Codes

Every rmt command, its options, what it prints in text and JSON, and the exit codes an agent loops on.

Commands

A BLUEPRINT ending in .yml or .yaml or containing a / is a file; anything else names a definition on the service. A shipped blueprint is run by its name, such as sales_commission.

Options for Any Command

At a terminal the CLI answers in text: outputs lined up by name, rows as tables, ✓ and ✗, and --trace as a tree of steps. Colour is on at a terminal unless NO_COLOR is set. Anywhere else (a pipe, a file, an agent) it answers in JSON, with every number as an exact string.

Exit Codes

check

rmt check BLUEPRINT

Lists problems with a blueprint as {"problems": [...]}: YAML that cannot be read, steps without a step type or with keys it does not take, formulas that cannot be read, names used before anything defines them, unknown calculations and tables, and outputs nothing produces. Exit 0 when there are none, 2 when there are.

$ rmt check broken.yml
✗ 3 problems
  • blow: input weapon has type text; input types are number, string, date, boolean, list
  • blow: step dealt uses armor, which is not an input or an earlier step
  • blow: step hp_after uses hp, which is not an input or an earlier step
$ rmt check broken.yml --json
{
  "problems": [
    "blow: input weapon has type text; input types are number, string, date, boolean, list",
    "blow: step dealt uses armor, which is not an input or an earlier step",
    "blow: step hp_after uses hp, which is not an input or an earlier step"
  ]
}

What it checks, in order:

flowchart TB
    a["valid YAML?"] --> b["at least one calculation?"]
    b --> c["input types known?"]
    c --> d["each step: snake_case name?"]
    d --> e["exactly one step type?"]
    e --> f["keys the type takes and needs?"]
    f --> g["formulas readable?"]
    g --> h["every name an input, table or earlier step?"]
    h --> i["calculations and tables it refers to exist?"]
    i --> k["a run once: are its inputs known by then?"]
    k --> l["name.output: does that run output it?"]
    l --> j["outputs produced?"]

run

rmt run BLUEPRINT [--facts FILE] [--calculation NAME] [--trace]
rmt run NAME [--version N|draft] [--facts FILE] [--calculation NAME] [--trace]

Runs a calculation (the first one unless --calculation names another) with facts read as JSON from --facts FILE or standard input, and prints its outputs. Numbers come back as exact strings. The blueprint is checked first, and a blueprint with problems exits 2 without running.

Facts must match the calculation’s inputs; problems with them come back as {"problems": [...]} with exit 1, as does a run that fails ({"error": "calculation > step: why"}):

$ echo '{"weapon": "axe", "rolled": "six", "hp": 12, "luck": 3}' | rmt run blow.yml
✗ 4 problems
  • fact weapon should be one of knife, club, not "axe"
  • fact rolled should be a number, not "six"
  • fact luck is not an input of blow; its inputs are weapon, rolled, armour, hp
  • facts need armour
$ echo '{"zone": "inner"' | rmt run fare.yml
✗ 1 problem
  • The facts are not valid JSON: expected ',' or '}' after object value, got: EOF at line 2 column 1

With --trace it prints {"outputs": ..., "steps": [...]}: every step’s value and how it was reached, the formula, the table row, or each rule with whether it matched, was chosen and the facts it read. A run over a list gives each row’s steps under rows, and a run once its steps under steps:

$ rmt run blow.yml --facts blow_facts.json --trace
dealt     5
hp_after  7

How it was worked out
  dice      1D8  row weapon club, damage 1D8
  dealt     5    MAX(0, MIN(rolled, DICE_MAX(dice)) - armour)
  hp_after  7    MAX(0, hp - dealt)

The text trace shows formulas, rows and row-by-row runs; the rules a step checked appear in the JSON.

Given a NAME rather than a file, it runs that definition on the service: the latest published version, or --version N or draft. Output and exit codes are the same.

test

rmt test BLUEPRINT CASES

Runs each case in the CASES YAML file and compares the outputs it expects. A case has a name, the facts to run, what to expect (any subset of the outputs) and optionally a calculation:

- name: a ghoul in the cellar
  facts: {sanity: 50, loss: 6}
  expect: {sanity_after: 44}

Numbers compare by value. Exit 0 when every case passes, 3 when any fails, 2 when the blueprint has problems or the cases file is not valid YAML. See Worked Examples.

$ rmt test blow.yml failing_cases.yml
✗ 1 of 3 cases failed

  ✗ a knife cannot deal more than its dice allow
      dealt: expected 4, got 3
      hp_after: expected 8, got 9

describe and guide

rmt describe lists step types with examples, input types, the cases format and formula functions. In text it prints each step type’s purpose and the function names; --json adds an example of each step type and how to call each function. rmt guide prints the guide to building a blueprint, the same loop as Getting Started.

Service Commands

Set RMT_API_KEY (create one at https://reason-me-this.com/app/api_keys). RMT_API_URL defaults to https://reason-me-this.com/api. Without a key, these commands exit 64 and say how to get one.

Any of them exits 69 when the service cannot be reached and 77 when it refuses the key. See The Hosted Service.

help

rmt help COMMAND or rmt COMMAND --help explains one command. rmt with no command, or an unknown one, prints the usage to standard error and exits 64.