The sub command

Command	Does
sub check file.sub [--strict]	find problems; --strict also fails on warnings
sub explain file.sub|file.wasm [--json]	what the script can do, in plain words (or as JSON)
sub manifest file.sub|file.wasm [--centcom]	the permission set and calls as JSON; --centcom shapes it for Centcom’s approval prompt
sub build file.sub [-o out.wasm] [--wasi]	compile to a WebAssembly module
sub run file.sub|file.wasm [--yes] [--root DIR] [--timeout S] [--max-output B] [-- args]	show the permissions, ask once, run
sub test file.sub [--yes]	run the test "name" { } blocks
sub fmt file.sub... [--check] [--stdout]	the canonical formatter (idempotent)
sub init [dir]	a small project: main.sub, a library, a test

Exit codes: 0 done, 1 failed or did not check, 2 usage, 3 a permission was denied while running, 4 the permissions were not approved.

A good error

error[E0201]: `run("git push")` is not allowed by `needs`
 --> fix.sub:12:3
   |
12 |   run("git push")
   |   ^^^^^^^^^^^^^^^ this command is not in the run list
   = help: add `run ["git push"]` to the `needs` block at the top of the file, or remove the call

Errors say what is wrong and show the exact fix, in words that both a person and a model can act on.

The approval

sub run prints the permission set in plain words and asks. --yes approves. always saves the set’s SHA-256 in .sub-allow next to the script, so the same permissions never ask again and different ones do. Without a terminal and without --yes, nothing runs.

Limits

--timeout SECS (30 for a request, 300 for a program; a program is killed and gives code 124), --max-output BYTES and --fetch-max BYTES (10 MiB each).

Language server

sub-lsp (in lsp/) speaks stdio LSP: diagnostics, hover with types and permissions, go to definition and completion for needs keys.