Develop

CLI Testing

The nilscript CLI explores the standard, generates an OpenAPI surface, and frames how you prove an adapter conforms. Conformance is behavioral — you drive your live shim with NIL sentences and assert standard-shaped responses.

Start with the CLI

Three commands explore the standard; no account, key, or waitlist required. Python ≥ 3.12 for the tooling — the standard itself is language-agnostic.

install

pip install nilscript

List & inspect verbs

A verb is only standard if it has a published profile. The profile is the contract — its arg schema, required fields, tier floor, outcomes, refusals, and reversibility tier.

verbs & profiles

nilscript verbs                            # the closed set of standard verbs
nilscript profile commerce.create_product  # arg schema, tier floor, outcomes
nilscript profile commerce.process_refund

Export OpenAPI

Generate an OpenAPI 3.1 spec for PROPOSE, COMMIT, QUERY, STATUS, EVENT, and ROLLBACK. Import it into Swagger or Postman, or feed it to a codegen tool.

export-openapi

nilscript export-openapi > nil.json
nilscript export-openapi --format json -o openapi.json
nilscript export-openapi --format yaml -o openapi.yaml

The profile is the source of truth

Refusal codes, arg validation, and tier floors all come from the profile. The OpenAPI surface is generated from it, not hand-authored.

Test against the corpus

Use the published conformance corpus and checklist as the spec of record. Drive your shim with NIL sentences — using the reference SDK or any HTTP client — and assert standard-shaped responses. Run the full matrix for every non-parked verb.

The thirteen rows

The behavioral conformance matrix asserts, end to end:

PROPOSE has no side effects.
Invalid args refuse (not an HTTP error).
Ambiguous references return ≤8 candidates.
COMMIT writes once and emits an EVENT with the entity.
A retried COMMIT is idempotent.
Expired or suspended proposals refuse.
STATUS replay works.
QUERY reads fresh.
EVENT HMAC is verified.
Sequence dedup works.
ROLLBACK compensation is real.
IRREVERSIBLE refuses honestly.
An unknown compensation token is refused.

Assert observable side effects

Conformance is behavioral, so the load-bearing rows (PROPOSE side-effect-free, COMMIT writes once, retried COMMIT idempotent) are verified out of band with a read-after-write against your system — not by trusting the HTTP response alone.