Reference

metais

metais reads, validates and renders METAIS packages, and helps author them.

metais version: 1.0.0. Specification: 1.0.

metais <command> [operands] [flags]

Golden paths

Consuming a package
inspect → read → schema → validate → render; preview from generated data with render --sample, or start from data generated by sample
Authoring a package
init → edit (preview with render --sample) → check → test → pack

Commands

Reading a package

metais inspect
Print what a supplier reads first: the package's identity, its guide, its inputs, outputs, references and examples, and the commands to run next.
metais ls
List the entries under a path of a package.
metais read
Print an entry of a package, or a range of its lines.
metais outline
List the headings of a Markdown entry, each with the lines of its section.
metais grep
Search a package's entries for a regular expression, with context.
metais schema
Print the package's combined input schema, or one input's schema, or list their fields.
metais extract
Write the entries the globs select to a directory.

Supplying and rendering

metais validate
Validate inputs against a package, and report every finding at once.
metais render
Render the package's outputs from the inputs supplied, into a directory or to standard output.
metais sample
Generate sample data from the inputs' schemas, and keep it as a data directory or an example.

Authoring

metais init
Write a new package's source directory: a greeting to learn from, or with --minimal one input and one template to replace.
metais check
Check a package without data, and report every finding of every step at once, or only the refusal of a package that cannot be read.
metais test
Render every example of a package and compare it with the outputs it should produce.
metais pack
Check and test a source directory, then write it as one package file.
metais unpack
Write a packed package's source directory, to edit it.

The tool

metais version
Print the tool's version and the specification versions it implements.
metais limits
List every resource limit, with its default, unit and class.
metais skill
Write metais's agent skill, which teaches a coding agent the golden paths, where the agent's harness reads skills.
metais help
Print the overview, a command's help, or a topic.

Global flags

--json
Print the result as one JSON document on standard output.
--color <when>
Colour human output: auto colours a stream that is a terminal when NO_COLOR is unset or empty; always and never override NO_COLOR. Values: auto, always, never. Default: auto.
-h, --help
Print help to standard output and exit 0; nothing else runs.
--version
Run metais version.

Topics

metais help inputs
Supplying a package's inputs, and which source wins.
metais help templates
Writing templates: the environment, every filter, and escaping.
metais help manifest
Every field of metais.yaml, inputs and outputs included.
metais help schemas
Writing schemas: every keyword and format, and rules across rows.
metais help globs
The patterns that select a package's entries.
metais help json
The JSON document every command prints with --json.
metais help exit-codes
What each exit status means.
metais help refusals
Every code a command may refuse with: metais help refusals <command>.
metais skill --print

Exit codes

0
Success, warnings included; help, version and limits.
1
An error in content: invalid inputs, a failing check or test, an output refused by its schema or its path, a package's own defect under an authoring command, or a warning under --fail-on warning.
2
A defect in metais itself (internal.error, or internal.memory when it stops a command holding more memory than it allows itself), or the Go runtime's status after a crash.
3
The command line is wrong: an unknown command or flag, a missing or extra operand, a malformed or repeated flag, or no command at all.
4
The package is refused: not found, unreadable, out of specification, a digest mismatch, an unsupported specification version or a package limit; or a package's own defect under a consuming command.
5
The destination is refused: not empty without --overwrite, a link or special file in the way, or a failed write.

Refusals

usage.bad_value
A global flag's value is missing or is not one it accepts, or a flag that takes no value is given one. Next: metais help: Lists every command, the global flags and the help topics.
usage.missing_command
No command is named. Next: metais help: Lists every command, the global flags and the help topics.
usage.repeated_flag
A global flag is given twice. Next: metais help: Lists every command, the global flags and the help topics.
usage.unknown_command
The command's name is not one metais has. Next: metais help: Lists every command, the global flags and the help topics.
usage.unknown_flag
A flag before the command's name that is not a global flag. Next: metais help: Lists every command, the global flags and the help topics.