CLI argument parser and help renderer for Crush programs — like
Python's argparse/click, but in the Crush language, for the Crush
language, driven by one declarative spec map.
// one spec map drives parsing, defaults, usage, --help, subcommands
let spec = { name: "greet", usage: "greet [options] [files...]", flags: [ { short: "-v", long: "--verbose", help: "say more" } ], options: [ { long: "--level", short: "-l", type: "int", default: 1, choices: [1, 2, 3], help: "verbosity" }, { long: "--name", type: "str", required: true, help: "who" } ], positionals: [ { name: "files", repeat: true, help: "extra files" } ] }
let args = facet_parse(spec) // bad input ⇒ error + usage + exit(2)
io.print("Hello, " + args.name + " (level " + conv.to_str(args.level) + ")")
That yields --help, -vh-style bundling, --level=2/-l2/-l 2,
positional collection, typed defaults and column-aligned help — all from
the spec. Runnable examples in demo/.
facet is one definitions-only file, so Crush's compile-time import (CRUSH-110)
works on it. Use the brace form, which binds the names bare:
import facet { facet_run, facet_fail } // only public names import; __facet_* do not
1. import + -L (scripts and projects):
crush-run run -L <facet dir> my_program.crush -- --help
# or: CRUSH_PATH=<facet dir> crush-run run my_program.crush -- --help(Plain import facet also works, but namespaces the functions: call
facet.facet_parse(spec); bare calls then fail with Undefined function.)
2. crush-pkg path dependency (see examples/consumer/):
[[dependencies]]
name = "facet"
path = "../facet"crush-pkg run -- --help # keep `import facet { ... }` in main.crush3. Concatenation (fallback for one-off scripts; the program must NOT have an
import facet line, or the names collide):
cat facet.crush my_program.crush > /tmp/my_program.crush
crush-run run /tmp/my_program.crush -- --helpEnv fallback needs the facet_env.crush companion. It imports
facet itself, so it is import-only: do not concatenate it with facet.crush (the
names collide). In your program:
import facet { facet_parse }
import facet_env { facet_env_apply }
Grant --env BEFORE the --, even for --help (the capability check covers the
whole program): crush-run run -L . --env prog.crush -- --name Ada.
fn main() {
// keep each map literal on one line until crush-ast CRUSH-345 lands
let add = { name: "add", help: "add an item", options: [ { short: "-p", long: "--priority", type: "int", default: 1, choices: [1, 2, 3], help: "1 = low, 3 = urgent" } ], positionals: [ { name: "text", required: true, help: "what to do" } ] }
let list = { name: "list", help: "show items", flags: [ { short: "-a", long: "--all", help: "include done items" } ] }
let spec = { name: "todo", version: "0.2.0", about: "A tiny todo list.", subcommands: [add, list] }
facet_run(spec, { add: |args| => cmd_add(spec, args), list: |args| => cmd_list(args) })
}
That gives todo --help, todo --version, todo add --help (the
subcommand's own options), typed and validated arguments, and exit status
0 / 2 everywhere, with no other code. Full program: demo/todo.crush.
| function | behavior |
|---|---|
facet_run(spec, handlers) |
facet_parse + facet_dispatch: the whole CLI in one call |
facet_parse(spec) |
parse sys.args(). Bad input ⇒ facet: <name>: <error> + usage (the subcommand's, if the error is in one) + exit(2). -h/--help ⇒ full help (or the subcommand's after it) + exit(0). --version/-V ⇒ name version + exit(0) when the spec has version. A spec with problems ⇒ facet: spec error: … + exit(70) |
facet_dispatch(spec, handlers, args) |
call handlers[args.subcommand] (or handlers.main without subcommands) with args, return its result; no handler ⇒ exit(70) |
facet_fail(spec, message) |
your own argument check, reported like facet's: message + usage + exit(2) |
facet_resolve(spec, argv) |
what argv asks for, without printing or exiting: { action: "help" | "version" | "error" | "run", text?, args?, spec? } |
facet_parse_debug(spec, argv) |
the parse alone over an argv array: { ok, data, error } (embedders + tests) |
facet_check_spec(spec) |
problems in a spec as lines ([] when fine): unknown keys such as requried, entries without long/short, a positional without name, an unknown option type |
facet_usage(spec) / facet_help(spec) |
the one-line usage / the full help text |
facet_version_text(spec) |
name version ("" without version) |
Handlers are closures or function references stored in a map:
{ add: |args| => do_add(args) } or { main: run }. (Call them through
facet_run/facet_dispatch: handlers.add(args) directly hits crush-ast
#362.)
Result map keys come from long (--build-dir ⇒ build_dir) unless the
entry sets name. Declared-but-unset options/positionals are present as
null; flags are false. _provided lists the keys that actually came
from argv (used by env fallback; handy for scripts).
Count flags: { short: "-v", long: "--verbose", count: true } yields an int
(0 when absent; -v 1, -vvv 3, -v -v 2, -vqv counts v twice). count
is allowed on flags only and cannot be combined with type or default;
--verbose=3 is a parse error. Help marks it "(repeatable)". It lands in
_provided only when it appears in argv.
required: true on a count flag means at least one occurrence (help: "(repeatable, required)").
spec: { name, usage?, version?, about?, epilog?,
flags?, options?, positionals?, subcommands?, groups? }
flags: { short?, long?, name?, default?, required?, count?, help? } // boolean; count: true => int
options: { short?, long?, name?, type?, default?, required?, // type: str|int|float|bool
choices?, env?, help? }
positionals: { name, type?, default?, required?, repeat?, help? }
subcommands: { name, usage?, help?, about?, epilog?, flags?, options?, positionals?, groups? }
groups: [ { exclusive: [...] } | { together: [...] } | { one_of: [...] } ]
Option groups (groups, top level or on a subcommand): each group object
has exactly one kind and lists 2+ members, a flag's or option's long name
("--json"), or its short name ("-j") when it has no long. Members must be
declared at the same level as the group. Violations are parse errors (exit 2):
exclusive: at most one given:--json and --table are mutually exclusive(the first two given, in declared order).together: if any is given, all must be:--user requires --pass(first given, first missing).one_of: at least one given:one of --a, --b is required. Exactly-one isone_ofplusexclusiveover the same members.
"Given" means it came from argv (it is in _provided): defaults do not count,
and facet_env values (filled after the parse) do not count either. Group
checks run after the required and choices checks, in declared group order.
facet_check_spec rejects unknown members, groups with fewer than 2 members
and group objects without exactly one kind (exit 70). --help does not list
groups yet.
Semantics: -- ends option parsing; -abc bundles boolean shorts;
-lv5 = -l v5; unknown option / missing value / bad type / choices miss /
missing required ⇒ exit 2. Options with env: need the
facet_env.crush companion (import-only; facet_env_apply(spec, args),
precedence argv > env > default, requires --env).
- PortableVm / scheduler (CVM1): fully verified — 77-check self test plus
demo runs (
crush-run). - FastVM / JIT: same shared capability implementations; the differential harness cannot yet wire capabilities for FastVM (it abstains), so untested.
- AOT backends: blocked upstream, not by facet — the Rust AOT lowerer
currently rejects
sys.args,sys.exitandconv.*; the C AOT backend rejects dynamic-text caps and cannot compiletry/catchorenv.getat all (CRUSH-xps-13).facet.crushdeliberately contains notry/catchand noenv.getso that consumers are not gated further; env fallback lives in the separate companion.
./test/run.shRuns each demo's --help through the import form, then concatenates facet.crush +
facet_test.crush for the self test (it needs the internals; needs crush-run on PATH). Design notes:
docs/plans/2026-10-31-facet-design.md.
Requires crush-ast ≥ 0.9.0.