CLI reference

Full reference for the aozora binary. For a guided tour, see CLI Quickstart.

Synopsis

aozora <SUBCOMMAND> [OPTIONS] [ARGS]

There are no global options beyond clap’s -h/--help and -V/--version; the input-shaping flags below are per-subcommand. All document subcommands accept - (or no path) to read stdin.

Colour follows the terminal and the NO_COLOR environment variable (miette honours it); there is no --no-color flag.

aozora check

aozora check [OPTIONS] [PATH]

Lex the source and report diagnostics. PATH of - (or omitted) reads from stdin.

The three formats:

• human — a graphical miette report: the source line, a caret under the span, the label, the help, and a link to the diagnostics catalogue.
• json — the aozora::wire diagnostics envelope, byte-identical to every other binding. The machine / agent path (the default when piped).
• short — one grep-able line: path:offset: severity[code]: msg.

Exit codes: 0 (parse succeeded; diagnostics may have been printed but were tolerated), 1 (--strict and at least one diagnostic), 2 (usage error), 3 (an Internal-source diagnostic fired — a library bug, not bad input; please report it).

aozora check src.txt                       # human on a TTY, json when piped
aozora check --strict src.txt              # any diagnostic -> exit 1
aozora check -E sjis crime.txt             # Shift_JIS source
aozora check --diagnostic-format short -   # one line per diagnostic, from stdin
cat src.txt | aozora check                 # json envelope (stderr is piped)

aozora fmt

aozora fmt [OPTIONS] [PATH]

Round-trip the source through parse ∘ serialize. Default prints the canonical form on stdout.

Exit codes: 0 (success, or no diff under --check), 1 (formatting mismatch under --check), 2 (usage error).

aozora fmt src.txt > formatted.txt
aozora fmt --check src.txt                 # CI gate
aozora fmt --write src.txt                 # in-place
cat src.txt | aozora fmt                    # stdin -> stdout

aozora render

aozora render [OPTIONS] [PATH]

Render the parsed tree to HTML on stdout. Accepts --encoding/-E.

aozora render src.txt > out.html
aozora render -E sjis crime.txt > crime.html
cat src.txt | aozora render -

The output is semantic HTML5 with aozora-* class hooks (no inline styles). See HTML renderer for the class-name reference.

aozora pandoc

aozora pandoc [OPTIONS] [PATH]

Project the parsed document to a Pandoc AST. Without --format/-t, prints Pandoc JSON to stdout (consumable by pandoc -f json -t …); with --format, spawns pandoc and pipes the JSON through it. Accepts --encoding/-E.

aozora pandoc src.txt | pandoc -f json -t epub3 -o out.epub
aozora pandoc src.txt -t latex > src.tex          # spawns pandoc directly

See Bindings → Pandoc.

Introspection subcommands

kinds, schema {diagnostics|nodes|pairs|container-pairs}, and explain <tag> print typed contracts and need no input file. They back the drift-gated wire artefacts; see Wire format.

Exit codes

Environment

See Reference → Environment variables for the full matrix.

See also

• CLI Quickstart — examples and the subcommand rationale.
• Notation overview — what the parser recognises.
• Diagnostics catalogue — the codes you’ll see in check’s output and how --diagnostic-format renders them.