Using a package
Someone gave you a .metais file. This guide takes you from that file to
the document it makes, and on to rendering it from a program.
It assumes metais is installed. Its example is a small
package, status-widget-1.0.0.metais, which renders an HTML fragment
showing a service's status. Every command works the same way on any
package: put your own file's name where this guide has
status-widget-1.0.0.metais.
Do not unzip the package. A .metais file is a zip archive, but
metais reads it in place and verifies every entry as it reads it. Every
command below takes the file exactly as you received it.
The route
- Find out what the package needs:
metais inspect. - Read what each input means, and list its fields:
metais schema. - Put your data in a data directory, one file per input.
- Check it:
metais validate. - Make the document:
metais render.
Every command ends with a Next: list of the commands to run after it, so
you can follow the route from the tool itself.
metais help <command> explains any command in full.
1. Find out what the package needs
metais inspect status-widget-1.0.0.metais
inspect verifies the whole package, then prints what it is: its title
and description, the author's guide, each input with the file names it is
read from, the outputs it renders, its references and examples, and the
commands to run next.
Read the guide. It is the author's own instructions for supplying the
data, and it often says where the data comes from. For this package, the
one input is status, read from status.json, and the one output is
status.html.
2. Read what each input means
metais schema status-widget-1.0.0.metais --fields
schema --fields lists every field of every input, one line each: where
the field is, its type, whether it is required, its constraints, and its
title. For this package:
/status object required additionalProperties=false Service status
/status/components array optional maxItems=20 minItems=1 Components
/status/components/* object optional additionalProperties=false -
/status/components/*/name string required maxLength=80 minLength=1 Component name
/status/components/*/state any required enum=["operational","degraded","outage","maintenance"] Component state
/status/message string optional maxLength=280 minLength=1 Message
/status/service string required maxLength=80 minLength=1 Service
/status/state any required enum=["operational","degraded","outage","maintenance"] State
/status/updated string required format="date-time" Updated
A field such as a component's name is required only when its parent,
here a component, is given.
Give it an input's name, metais schema status-widget-1.0.0.metais status --fields, to list one input. Leave out --fields to print the whole JSON
Schema, with each field's description.
If someone asks you what the package needs from them, this listing is the answer: every input, and every required field of each.
Many packages also give an input a meaning document, which explains what
the data is and what good data looks like. When a package has one,
inspect lists it in its Next: lines as a metais read of the
package's inputs/ entry: run it, and read the whole document before you
gather the data. This package's single input needs none.
3. Put your data in a data directory
Make a directory, here data, and put one file in it for each input,
named as inspect listed it: data/status.json.
{
"service": "Payments API",
"state": "degraded",
"updated": "2026-10-23T09:30:00Z",
"message": "Card payments are slower than usual."
}
The data is yours to supply. A real document is made only from real facts. If you do not have a value the package requires, find it or ask for it. Do not guess it, and do not copy it from the package's examples: an example is the author's illustration, kept to test the package, and none of its values are yours.
4. Check your data
metais validate status-widget-1.0.0.metais --data data
validate reports every problem in one run, each with the file, line and
column it is at, the field it concerns, the rule it breaks and how to fix
it:
status.json:4:14: error: Updated is not in the date-time format. [input.format]
at /status/updated (input status: Service status)
…
hint: Write a value in the date-time format that fits the field's description: …
1 error, 0 warnings, 0 info
Fix what it reports and run it again, until it reports 0 errors.
5. Make the document
metais render status-widget-1.0.0.metais --data data --out widget
render checks the data again, renders every output in memory, and
writes them into the new directory widget only when all of them
succeed. It lists each file it wrote, with its size and digest.
--dry-runlists what it would write, and writes nothing.--outmust name a new or empty directory. To render again into the same one, add--overwrite: it replaces the files the render writes, and leaves every other file there alone.
Rendering is pure. Nothing from the package runs, nothing is fetched from the network, and the same package and data give the same bytes on every platform.
See what a package produces, before you have the data
To preview a package, render it from data that metais generates from
the package's schemas:
metais render status-widget-1.0.0.metais --sample --out preview
The values are fictional, so the preview shows the document's shape, not your document. Show it as a preview, and never as a real document.
The package's examples are not a preview: they are the author's tests.
Start from generated data
To start your data from a file of the right shape, generate one and replace every value with your own:
metais sample status-widget-1.0.0.metais --out data
--seed <n> generates different values, for when you want fictional data
of your own rather than the default set:
metais sample status-widget-1.0.0.metais --seed 7 --out data7
Render from a program
A package is often filled in by a program: a nightly job that fetches the
status and renders the widget. The job writes its data where the package
expects it, and runs render. Here is the job as render-status.sh:
#!/bin/sh
# Renders the status widget from data/status.json into widget/.
set -eu
metais render status-widget-1.0.0.metais --data data --out widget --overwrite
render validates the data first, and writes nothing when any of it is
in error, so the job never publishes a broken document. Its exit status
says what happened: 0 when the document was written, 1 when the data
is invalid, and 4 or 5 when the package or the destination was
refused. metais help exit-codes lists every one.
To test the job before it has real data, give it generated data:
metais sample status-widget-1.0.0.metais --out data
./render-status.sh
A program that wants to read the result can add --json to any command,
which prints one JSON document: whether it succeeded, every finding with
its stable code, and what was written. metais help json describes every
document.
Escape hatches
The route above is the one to follow. When it does not fit, these are there:
-
Values on the command line.
--set /status/state=outagesets one value over the data directory's;--set-jsonsets a JSON value, and--inputs-jsonsupplies whole inputs.metais help inputssays which source wins. -
One file to standard output.
metais render status-widget-1.0.0.metais --data data --out - --only status.htmlwrites that file's bytes alone. -
Reading the package.
metais ls,metais read,metais outlineandmetais greplist, print, outline and search its entries, in place:metais ls status-widget-1.0.0.metais -r metais grep status-widget-1.0.0.metais degraded references/ -
Changing the package itself. That is writing a package, not using one:
metais unpackturns it back into a source directory. Writing a package explains the rest. -
An agent doing this for you.
metais skillinstalls a skill that teaches a coding agent this route.