Skip to content
Arne K. (TRC-Loop) edited this page Nov 14, 2026 · 3 revisions

CLI

The rustyon command formats, validates, queries and converts RON files.

Install

go install github.com/peltonapp/rustyon-go/cmd/rustyon@latest

The CLI is its own Go module, github.com/peltonapp/rustyon-go/cmd/rustyon, with its own version tags (cmd/rustyon/vX.Y.Z). The library stays free of dependencies; only the CLI needs the YAML and TOML libraries. The repository joins both modules with a committed go.work file, so a build inside a clone always uses your local copy of the library.

There is no cmd/rustyon/v* tag yet (the first one will be cmd/rustyon/v1.1.0), so @latest resolves to a pseudo-version of the newest commit on main and rustyon version prints that pseudo-version. Such a build uses the library version pinned in cmd/rustyon/go.mod (v1.0.0), not the workspace copy, so details like error message wording can differ from this page. To get exactly what this page shows, build from a clone:

git clone https://github.com/peltonapp/rustyon-go.git
cd rustyon-go
make build            # writes ./bin/rustyon

Once the CLI is tagged, binaries for Linux, macOS, Windows and FreeBSD are attached to the releases tagged cmd/rustyon/v*.

Usage

rustyon <command> [flags] [file ...]
Command Purpose
fmt format RON files, keeping comments
validate check that RON files are well formed
to-json convert RON to JSON
from-json convert JSON to RON
to-yaml convert RON to YAML
from-yaml convert YAML to RON
to-toml convert RON to TOML
from-toml convert TOML to RON
get print the value at a path, such as items[0].name
version print the version
help print the usage text

Without file arguments, every command reads from standard input (shown as <stdin> in messages). Run rustyon <command> -h for the flags of a command. Flags come before the file names.

Exit codes

Code Meaning
0 success, including -h and help
1 an error: invalid input, a failed conversion, a get path that does not exist, or a file that cannot be read or written
2 usage error: no command, an unknown command, an unknown flag, fmt -w without files, to-yaml -indent 0, a malformed get path, or more than one file for a command that takes one

Error output

Syntax errors are printed as file:line:col: message, followed by the source line and a caret under the column:

$ rustyon validate broken.ron
broken.ron:3:16: expected ',' or ')'
 3 |     size: (800 600),
   |                ^

line is 1-based and col counts Unicode code points. The caret is placed by code point, and tabs before the caret are repeated in the caret line so it lines up at any tab width. Lines longer than 80 characters are trimmed around the error column and marked with .... Errors that are not syntax errors (conversion failures, YAML and TOML parse errors) print as name: message on one line. Problems with the command line or an unreadable file print as rustyon: message.

$ printf '(a: \xe2\x82\xac 1)\n' | rustyon validate
<stdin>:1:5: unexpected character '€'
 1 | (a: € 1)
   |     ^

fmt

rustyon fmt [-w] [-l] [-indent str] [file ...]

Formats each input with the Formatter and writes the result to standard output.

Flag Default Effect
-w off Write the result back to the file instead of standard output. Files that are already formatted are not touched; the file mode is kept. Requires file arguments.
-l off List the names of inputs whose formatting differs, instead of printing the formatted text.
-indent str four spaces Indentation for each nesting level.

-w and -l can be combined to rewrite files and list the ones that changed. Inputs with syntax errors are reported on standard error with a caret and the remaining inputs are still processed; the exit code is then 1. A file that cannot be read stops the command before any output.

Given config.ron:

// window settings
(title:"Demo", // shown in the title bar
size:(800,600), fps: Some(60))
$ rustyon fmt config.ron
// window settings
(
    title: "Demo", // shown in the title bar
    size: (800, 600),
    fps: Some(60),
)
$ rustyon fmt -l config.ron broken.ron
config.ron
broken.ron:3:16: expected ',' or ')'
 3 |     size: (800 600),
   |                ^
$ echo $?
1
rustyon fmt -w config.ron          # format in place
rustyon fmt -w -l *.ron            # format in place and list changed files
rustyon fmt -indent "	" config.ron  # indent with tabs

validate

rustyon validate [-q] [file ...]

Parses each input and prints name: ok on standard output for valid ones. Errors go to standard error in the caret format shown above. The exit code is 1 if any input is invalid.

Flag Default Effect
-q off Only report errors; print nothing for valid inputs.
$ rustyon validate config.ron broken.ron
config.ron: ok
broken.ron:3:16: expected ',' or ')'
 3 |     size: (800 600),
   |                ^
$ echo $?
1

$ echo '[1, 2]' | rustyon validate
<stdin>: ok

$ rustyon validate trunc.ron
trunc.ron:2:17: expected ',' or ')'
 2 | size: (800, 600)
   |                 ^

validate checks syntax only. It does not check a document against any Go or Rust type. The grammar is the one of ron-rs, see RON Syntax.

to-json

rustyon to-json [-indent str] [file]

Converts one RON document to JSON with ronjson.ToJSON and prints it followed by a newline. Takes at most one file.

Flag Default Effect
-indent str two spaces Indentation; an empty string gives compact output.
$ rustyon to-json config.ron
{
  "title": "Demo",
  "size": [
    800,
    600
  ],
  "fps": 60
}

$ rustyon to-json -indent "" config.ron
{"title":"Demo","size":[800,600],"fps":60}

Values JSON cannot represent fail with exit code 1:

$ echo 'NaN' | rustyon to-json
<stdin>: ronjson: NaN cannot be represented in JSON

from-json

rustyon from-json [-structs] [-indent str] [file]

Converts one JSON document to RON with ronjson.FromJSON and prints it followed by a newline. Takes at most one file.

Flag Default Effect
-structs off Write JSON objects whose keys are all valid identifiers as RON structs (key: value) instead of maps {"key": value}.
-indent str four spaces Indentation; an empty string gives compact output.
$ echo '{"name": "Ferris", "max_hp": 100, "tags": ["crab"], "pet": null}' | rustyon from-json -structs
(
    name: "Ferris",
    max_hp: 100,
    tags: [
        "crab",
    ],
    pet: None,
)

$ echo '{"name": "Ferris", "the key": 1}' | rustyon from-json -structs -indent ""
{"name":"Ferris","the key":1}

In the last example "the key" is not an identifier, so the object stays a map even with -structs.

to-yaml and from-yaml

rustyon to-yaml [-indent n] [file]
rustyon from-yaml [-structs] [-indent str] [file]

Both take at most one file. to-yaml goes through the JSON mapping, so YAML loses the same things JSON does: struct and variant names, chars, the difference between None and unit, and so on. Output is block style YAML in the field order of the RON document.

Flag Command Default Effect
-indent n to-yaml 2 Spaces per nesting level, at least 1 (0 is a usage error).
-structs from-yaml off Write mappings whose keys are identifiers as structs instead of maps.
-indent str from-yaml four spaces Indentation of the RON output; an empty string gives compact output.

Given game.ron:

#![enable(implicit_some)]
GameConfig(
    title: "Rusty Game",
    window_size: (800, 600),
    difficulty: Hard,
    volume: 0.8,
    save_path: None,
    tags: ["fast", "yes"],
    players: {"alice": (level: 3), "bob": (level: 5)},
    items: [(name: "sword", damage: 7), (name: "bow", damage: 4)],
    config: (port: 8080),
)
$ rustyon to-yaml game.ron
title: Rusty Game
window_size:
  - 800
  - 600
difficulty: Hard
volume: 0.8
save_path: null
tags:
  - fast
  - "yes"
players:
  alice:
    level: 3
  bob:
    level: 5
items:
  - name: sword
    damage: 7
  - name: bow
    damage: 4
config:
  port: 8080

$ rustyon to-yaml -indent 4 config.ron
title: Demo
size:
    - 800
    - 600
fps: 60
$ printf 'name: Ferris\nmax_hp: 100\ntags: [crab]\npet: ~\n' | rustyon from-yaml -structs
(
    name: "Ferris",
    max_hp: 100,
    tags: [
        "crab",
    ],
    pet: None,
)

$ printf 'a: 18446744073709551615\nb: 1e3\n' | rustyon from-yaml -structs -indent ""
(a:18446744073709551615,b:1000)

Caveats:

  • Quoting. The strings y, yes, n, no, on and off (any case) are written in double quotes, because YAML 1.1 parsers read them as booleans. Other strings are quoted only when YAML needs it, so a string such as "12" or "true" comes out quoted and stays a string.
  • Big integers. Integers up to 128 bits are written with all their digits, and plain digit runs are read back as integers even beyond 64 bits.
  • NaN and infinity cannot be converted and fail with an error.
  • One document. from-yaml converts a single document. A stream with a second document (---) is an error, and so is empty input.
  • Keys. Only scalar mapping keys are supported. Aliases are expanded. Timestamps and binary data keep their text as strings.
$ printf 'a: 1\n---\nb: 2\n' | rustyon from-yaml
<stdin>: YAML input has more than one document

to-toml and from-toml

rustyon to-toml [file]
rustyon from-toml [-structs] [-indent str] [file]

Both take at most one file. to-toml also goes through the JSON mapping. from-toml takes the same -structs and -indent flags as from-json.

$ rustyon to-toml game.ron
difficulty = 'Hard'
tags = ['fast', 'yes']
title = 'Rusty Game'
volume = 0.8
window_size = [800, 600]

[config]
port = 8080

[[items]]
damage = 7
name = 'sword'

[[items]]
damage = 4
name = 'bow'

[players]
[players.alice]
level = 3

[players.bob]
level = 5

Note that save_path: None is gone and the keys are sorted.

$ printf 'title = "Demo"\nwhen = 2026-11-14T10:00:00Z\nday = 2026-11-14\n[server]\nport = 8080\nhost = "x"\n' | rustyon from-toml -structs
(
    day: "2026-11-14",
    server: (
        host: "x",
        port: 8080,
    ),
    title: "Demo",
    when: "2026-11-14T10:00:00Z",
)

Caveats:

  • Top level. TOML needs a table at the top level, so the RON document must be a struct or map.
  • None. TOML has no null. A None (or unit) value in a struct or map is left out of the output. A None or unit inside an array cannot be expressed and is an error.
  • 64-bit integers. TOML integers are 64 bit. A larger integer is an error.
  • Key order. TOML tables are unordered, so both directions write keys sorted.
  • Dates and times in TOML become strings in RON (RFC 3339 text).
$ echo '[1,2]' | rustyon to-toml
<stdin>: TOML needs a struct or map at the top level

$ echo '(a: [None, 1])' | rustyon to-toml
<stdin>: a[0]: TOML cannot represent null (None or unit) inside an array

$ echo '(a: 170141183460469231731687303715884105727)' | rustyon to-toml
<stdin>: integer 170141183460469231731687303715884105727 does not fit into 64 bits, which TOML requires

get

rustyon get [-indent str] path [file]

Prints the RON value at a path, followed by a newline. Takes a path and at most one file. Exits with 1 if the path does not exist and with 2 if the path is malformed.

Flag Default Effect
-indent str four spaces Indentation; an empty string gives compact output.

A path is built from three kinds of steps:

Step Selects
.name a struct field, or a map entry whose key is the string or identifier name. The leading dot is optional.
[N] a list or tuple element (a negative N counts from the end), or a map entry with integer key N
["key"] a map entry with that string key (Go escapes) or an identifier key of the same name, or a struct field

Steps chain: items[0].name, .config.port, players["alice"], tags[-1]. An empty path or . selects the whole document. Some(x) is looked through, so a step applies to x; None has nothing to step into. Names cannot contain ., [ or ]; use ["key"] for those.

Using game.ron from above:

$ rustyon get 'items[0].name' game.ron
"sword"

$ rustyon get .config.port game.ron
8080

$ rustyon get 'players["alice"]' game.ron
(
    level: 3,
)

$ rustyon get 'tags[-1]' game.ron
"yes"

$ rustyon get -indent "" items game.ron
[(name:"sword",damage:7),(name:"bow",damage:4)]

$ rustyon get . config.ron
(
    title: "Demo",
    size: (800, 600),
    fps: Some(60),
)

$ echo '(m: {1: "one", Foo: 2})' | rustyon get 'm[1]'
"one"

$ echo '(m: {1: "one", Foo: 2})' | rustyon get 'm.Foo'
2

Quote paths in the shell, since [ and " are special there. A missing path names the step that failed:

$ rustyon get missing game.ron
rustyon get: game.ron: not found: .missing: no field "missing" (at .)
$ echo $?
1

$ rustyon get 'items[5]' game.ron
rustyon get: game.ron: not found: .items[5]: index 5 out of range, length 2 (at .items)

$ rustyon get save_path.x game.ron
rustyon get: game.ron: not found: .save_path.x: value is None (at .save_path)

$ rustyon get 'tags[' game.ron
rustyon get: invalid path "tags[": missing ] after offset 4
$ echo $?
2

version and help

rustyon version     # also: -version, --version
rustyon help        # also: -h, -help, --help

version prints rustyon followed by the release version, or the module version from the build information, or (devel).

Using it in CI

# Fail the build when a file is not formatted or invalid.
test -z "$(rustyon fmt -l configs/*.ron)"
rustyon validate -q configs/*.ron

# Read one setting from a file.
port="$(rustyon get .server.port configs/prod.ron)"

fmt -l exits with 0 even when files need formatting, so check its output, as above.

Clone this wiki locally