Scripts and agents look up exit codes, the --json envelope, global flags, environment variables, file verification, the document and picture verbs, where local state lives and shell completion here. Start at the lolly CLI page.
Exit codes
Every command returns one code per outcome, so a pipeline can branch on the code instead of reading stderr. The meanings are fixed: a new code can be added, but an existing code does not change meaning without a major version.
| Code | Name | Meaning | What to do |
|---|---|---|---|
| 0 | OK | The requested thing was produced. | Carry on. |
| 1 | FAILED | It was possible, it ran and it failed: a hook threw, or the render produced nothing. A gate inside a tool's own hook (--verify) fails this way too. | Read the message; fix the input or the tool. |
| 2 | USAGE | Wrong invocation: unknown tool, undeclared format, missing argument, unreadable path or a learning build source that only a change to the module can fix (LEARNING_NO_RENDITION, LEARNING_DEVICE_FILE, LEARNING_LOCAL_PATH). | Fix the command line. |
| 3 | UNAVAILABLE_HERE | Impossible in this installation: no browser, an unmet capability, a paint-tier render that could not produce the file, an on-device model that is not staged (MODEL_NOT_STAGED, MODEL_NOT_INSTALLED), a runtime this install does not carry (CAPABILITY_UNAVAILABLE), --hdr with --durable (HDR_DURABLE_UNAVAILABLE) or a learning build source this install cannot render (LEARNING_FORMAT_UNAVAILABLE, MOTION_RENDERER_UNAVAILABLE). | Retry on a runner that has what is missing. |
| 4 | REFUSED | A protective check this shell ran said no. | Read the findings; do not ship the file as it is. |
| 5 | NOT_FOUND | A legitimate negative answer: validate found no credential, rebrand compile has a deck that needs review, check has findings to review and no errors. With --json, the envelope carries the full result and ok: false. | Look at the result; it is an answer, not an error. |
| 6 | AUTH | A missing or wrong password or passphrase. | Supply the secret. |
| 70 | INTERNAL | An unclassified exception: a bug in Lolly. | Report it; do not retry. |
Everything that exits 4
- the bytes were not the format claimed, or a credential is present but broken;
--strictpromoted a gate-class warning, or--depth=floatwas asked of an 8-bit render;lolly checkfound an error, or any warning under--strict(the writing score,verify.writing-score, never counts);lolly packagemet a Lolly Design document whose pictures have no bytes or are not catalog ids, or an output that already exists;lolly composerefused a spec (with the JSON pointer of the key) or met an output that already exists;lolly intentrefused a request, or a surface is not ready. The full answer is still on stdout;- a Lolly Design document's authoring keys could not be lowered (
AUTHORING_INVALID); --passwordon a file that cannot carry one (PASSWORD_UNAVAILABLE), or a file that came back without its lock (PASSWORD_NOT_APPLIED). Nothing is written;- a render whose sources still need a rights decision; it still writes its file.
learning builddoes the same and lists those blocks inresult.rightsDecisionsRequired.
Messages go to stderr; --verbose (or DEBUG=1) adds stack traces. An input that fails validation lists each field at fault. When a command takes a list of files, the exit code is the worst file's.
The --json envelope
--json puts one JSON document on stdout and nothing else; every human line moves to stderr. It works on list, describe, assets, validate, smoke, batch, preflight, models, mix, speak, transcribe, ocr, detect-ai, reword, rebrand, read, check, compose, look (with --output), sample, trace, system, start, files, prepare, learning, intent, projects and reports, and on measure --text, measure --text-layers and package of a Lolly Design document.
It is not available on a render, because a render's stdout is the file; asking for both is a usage error. lolly speak --out=- --json is refused for the same reason.
Every command uses this envelope, except ocr, detect-ai and reword, which emit a smaller { "ok": true, "command": …, … } document with no schemaVersion or warnings:
{
"schemaVersion": 1,
"command": "validate",
"ok": true,
"engine": "1.115.0",
"cli": "0.1.0",
"result": { },
"warnings": [{ "code": "UNKNOWN_FLAG", "message": "…", "kind": "usage" }],
"error": null
}The two version strings are whatever this installation runs; read them from the envelope.
The envelope covers the failure path too. A missing file, an unknown tool or a crash still leaves a complete document on stdout, so lolly … --json > r.json never leaves an unparseable file. On that path result is null and error is filled in:
"error": { "code": "UNAVAILABLE_HERE", "exit": 3, "kind": "FORMAT_UNAVAILABLE", "message": "…" }Branch on error.kind and error.exit, never on error.message, whose wording can change. ok mirrors the exit code, so a valid answer can be ok: false: validate reporting no credential exits 5 with a full result.
Compatibility rules. Keys may be added inside result, error and warnings at any time, and enum values may be added, so ignore unknown keys and keep a default branch. schemaVersion goes up only when a key is removed, retyped or changes meaning.
Discovery, for an agent
lolly list --json # every tool, and what this installation can do
lolly describe qr-code --json # one tool's full input schemalist --json carries a result.environment block: the engine and CLI versions, the content root, the host capabilities this shell provides, the browser-free formats and a per-tier report (domFree, raster, desktop, browser, images) with the reason for each missing tier. Each tool carries capabilities, unmetCapabilities, nativeFormats and runnableHere, so an agent can tell that screencap will exit 3 here before it tries.
describe --json returns each input's declared spec plus three things the manifest cannot know: flag (the command-line spelling), urlParam (the compact alias, when the tool declares one) and syntax (how to write a non-scalar value). For an input whose id is also a reserved flag (width, height, format), flag is --input.<id>= and shadowedByReservedParam is true, because the bare id would set the export size instead.
Global flags
These work on every command:
| Flag | Meaning |
|---|---|
--json | One JSON envelope on stdout instead of human text (above). Not valid on a render. |
--quiet | Suppress non-error stderr: progress notes, warnings, the byte-count line. Errors still print. |
--verbose | Diagnostics and stack traces. DEBUG=1 is an alias. |
--strict | Promote this run's warnings to a failure after the work is reported: exit 2 for a usage-class warning, 4 for a gate-class one. |
-h, --help, -v, --version | Recognised anywhere in the arguments. |
-- | Ends option parsing. Everything after it is positional, which is the only way to pass a longtext value that itself starts with --. |
A flag that takes a value is refused in its bare form rather than read as "1": lolly qr-code --output is an error, not a file called 1. NO_COLOR is honoured alongside the terminal check. Render flags are listed in Render with the CLI. One of them, --allow-browser-free, accepts a picture drawn without a browser that may differ from the app's, where the CLI would otherwise refuse it; the CLI warns and records the acceptance in the Content Credential, and still refuses a picture that would be wrong.
Environment variables
Where a flag and a variable set the same thing, the flag wins. --trust-anchor is the exception: it adds to the roots in LOLLY_TRUST_ANCHOR. When the variables that decide where the CLI reads and renders are set, lolly list --json reports them under result.environment.env.
| Variable | Effect |
|---|---|
LOLLY_ROOT | The content root to read tools and the catalog from (A standalone CLI). |
LOLLY_PROFILE | The content profile: which tool packs and catalog a checkout uses. |
LOLLY_STATE_DIR | Where saved sessions and terminal design systems live (below). LOLLY_TUI_DIR is the old name. |
LOLLY_RENDERER | auto (default), desktop or chromium: which paint renderer to use. |
LOLLY_DESKTOP_BIN, LOLLY_RENDER_SERVER | An app executable in an unusual place, or the app's render.json directly. |
LOLLY_BROWSER_PATH, LOLLY_BROWSER_CHANNEL | A browser binary to use, or an installed channel such as chrome, instead of the downloaded Chromium. |
PLAYWRIGHT_BROWSERS_PATH | Where lolly install-browser puts Chromium. |
LOLLY_WEB_DIST, LOLLY_WEB_BASE | A built web shell somewhere else, or the address of one you serve. |
LOLLY_EXPORT_IDLE_TIMEOUT, LOLLY_CLI_TIMEOUT | Seconds without progress before a Chromium export stops; the desktop renderer's timeout. |
LOLLY_TIER_B_DEBUG | 1 keeps the headless page's logs, like --tier-b-debug. |
LOLLY_TRUST_ANCHOR | Extra trust roots for validate, as a PATH-style list. |
LOLLY_SIGN_KEY, LOLLY_SIGN_CERT, LOLLY_SIGN_KEY_PEM, LOLLY_SIGN_CERT_PEM, LOLLY_SIGN_KEY_PASSWORD | A signing identity (Signing from the terminal). |
LOLLY_MODELS_DIR, LOLLY_MODELS_BASE | Where on-device models are read from, and the host they are fetched from. |
LOLLY_ORT_EP, LOLLY_ORT_THREADS | An accelerated model provider (coreml, cuda), and a thread cap per model session. |
LOLLY_HOOK_WORKER | 1 runs tool hooks in a worker thread. |
SOURCE_DATE_EPOCH | The time written into .lolly zip entries by lolly package. |
NO_COLOR | Plain text output. |
Verify a file (lolly validate)
lolly validate is the read side of Content Credentials and runs on this machine:
lolly validate ./poster.pdf
lolly validate ./poster.pdf --json
lolly validate ./poster.png --deep
lolly validate ./poster.pdf --trust-anchor=./corp-root.pem
lolly validate ./poster.svg --no-default-anchors # trust only what you pinnedThe summary says whether the file was made with Lolly and is unchanged since. The exit code is 0 when the file matches what was signed, even with an expired certificate. Lolly signs with short-lived on-device certificates, so any other rule would fail every gate on Lolly's own correct output within a month. The code is 4 when a credential is present and the bytes no longer match the credential, 5 when there is no credential and 2 when the path could not be read. --strict makes an expired certificate exit 4. --require=none turns off verdict-based exit codes ("just tell me what is in this file").
Which anchors produced the verdict
Every report says which anchor set it used. The default is the Lolly CA root, the vendored C2PA known-certificate list (camera makers and the big generators) and anything you pinned. The app's Verify view uses the same set:
$ lolly validate ./qr.svg
./qr.svg [svg]
✦ Made with Lolly - credential intact, file unchanged since export
…
ℹ signingCredential.untrusted - signing certificate untrusted - an ephemeral on-device key, not a CA-issued identity
Trust anchors: C2PA known-certificate list (54) · pinned: none · Lolly CA root
$ lolly validate ./qr.svg --no-default-anchors
…
Trust anchors: no built-in anchors · pinned: none · Lolly CA root NOT pinnedBoth exit 0. The file is signed with an on-device key that chains to nothing. That is expected for a terminal render and is not damage. Signing from the terminal shows how to sign with a name a recipient can verify.
Every lolly validate flag
| Flag | Meaning | |
|---|---|---|
--json | The shared envelope. result.files[] holds one record per file: verdict (the stable slug), resolved (the engine's verdict), report (the full verifier output), metadata (the --metadata report, or null) and anchors. A file that could not be read gets a record with its own error, so one typo does not hide nine results. | |
--deep | Also run the neural pixel-watermark scan (TrustMark, Content Seal and the Lolly durable mark). Needs the headless Chromium and a built web shell, and is advisory: it never changes the exit code. | |
--trust-anchor=<root.pem> | Trust another root certificate, such as your organisation's CA. Repeatable; $LOLLY_TRUST_ANCHOR adds more as a PATH-style list (: on Unix, ; on Windows), and a leading ~ expands. A pinned root that cannot be read stops the run (exit 2) rather than quietly weakening the verdict. | |
--no-default-anchors | Trust only what you pinned. With nothing pinned, every signer reads untrusted: the bare-trust check, which confirms a green verdict came from a root you chose. | |
| `--require=credential\ | none` | credential (the default) gates the exit code on the verdict; none reports what is in the file and exits 0 when it could be read. |
--metadata | Also report what else is in the file (below). | |
--rebuild=<session.lolly> | The reproducibility receipt: render the session again here and report IDENTICAL (exit 0) or DIFFERENT (exit 1) with every reason it could check: engine version, tool version, a font that resolves differently, a different design system or the offset where the content first differs. svg, emf, eps, dxf and csv only; a raster or PDF is refused with exit 2, because those bytes come from a browser engine. See Reproducibility. |
--metadata: what else is in this file
Use --metadata before you send a file on. Besides the credential verdict, it reports:
- Embedded metadata: EXIF, XMP and IPTC fields, a GPS fix if the file records one, an AI source-type declaration if the generator wrote one and any bytes after the container's end. Fields the engine considers personally identifying are marked.
- PDF structure: pages, page sizes, fonts, images, annotations, the Info dictionary, whether an XMP packet is present and how much text can be extracted. Pages with no text layer are named as scans that need OCR.
- Text in the file but not visible on the page: a failed redaction, where a black bar covers words that are still in the content stream. The report says where those words are and quotes them back. It cannot say why they are there.
lolly validate ./contract.pdf --metadata
lolly validate ./photo.jpg --metadata --require=none # report only, never a gate--metadata | --deep | |
|---|---|---|
| Reads | Embedded fields, PDF structure, hidden text | Pixel watermarks: TrustMark, Content Seal, the Lolly durable mark |
| Needs | Nothing extra | The headless Chromium and a built web shell |
| Changes the exit code | Under --strict: hidden text, a GPS fix or bytes after the container exit 4 | Never |
- No invisible or neural watermark detection runs under
--metadata. SynthID is not detected by Lolly at all. - The hidden-text pass covers one case: text under an opaque shape that covers most of the line. Text hidden by an invisible render mode, a clip path, white-on-white colour or a bar drawn tight around the glyphs is not reported.
- PDFs are read to 25 pages. A longer document's report says how many pages it read and claims nothing about the rest.
- A file too broken to parse gives fewer findings plus an explicit "this report is incomplete" line, never a crash and never a clean bill of health.
Every report ends with what it did not check, because nothing found is not the same as nothing there.
Document verbs
The versioned document API works without rendering a tool to pixels:
lolly schema qr-code
lolly compile qr-code --inputs=inputs.json > document.json
lolly validate document.json --document
lolly inspect document.json
lolly measure document.json
lolly diff before.json after.json
lolly optimize export.png --format=png --output=clean.png
lolly package document.json --output=session.lollycompile emits the hydrated, typed document plus warnings, and schema emits its JSON Schema. inspect, measure and diff read meaning, not pixels. optimize reports the fixed stages it ran when writing a file, and package writes an application/vnd.lolly+zip share envelope.
A logical asset input such as image://brand/logo, catalog://lolly/logo/primary or library://user/upload/… resolves through the same host bridge as an ordinary render. A CLI run on a device does not resolve credentialled cms:// or governed net:// references; those need Lolly Work.
measure and package also take a Lolly Design document directly, and inspect --forensic reports located AI clues and their coverage (AI evidence in Lolly Verify). Rebuild a deck from the terminal covers the Lolly Design forms.
Start from what the piece has to do
lolly intent takes a JSON file, or - for standard input, that says what a piece has to do, where it will be seen and what it has to say. It answers with the tool for each surface, the input values, what is missing and why. --render makes a file for each ready surface and writes the answer next to the files as intent-resolution.json. Start from what the piece has to do has the format.
lolly intent certificate.json
lolly intent certificate.json --json
lolly intent certificate.json --render --out-dir=./out
lolly intent certificate.json --render --record-prompt
lolly intent certificate.json --render --no-record-intentWith --render, each file's Content Credential records the purpose, surface, tool, language, rules and vocabulary versions and the intent digest, with occasion, audience, region and the prompt as fingerprints only. --record-prompt records the prompt's own words instead of its fingerprint. --no-record-intent records nothing about the intent. --c2pa=off writes no credential; --c2pa=<days> sets its lifetime. Each run says what it recorded, read back from the finished file. --json gives the same as intentRecord on each entry in rendered. What goes in the file has the detail.
Bring a design in from another service (lolly import)
lolly import <template.json> turns a Bannerbear V5 image template into a Design document on this device and prints what was left out, one note per line. --output=<file> writes the frames and report. --mapping=<file> writes the entry lw render-api reads. --json prints the result. See Bannerbear templates. Bannerbear V2 and Placid return no design, so lolly import refuses them.
The importer is built from public documentation and has not run against a live account.
Look at a picture in its own coordinates
The MCP server's looking tools are also CLI verbs on the same code, so a script sees what an agent sees. Each takes an SVG, PNG, JPEG, GIF or WebP file, or - for standard input:
lolly design --z=… --export=svg | lolly look - --output=look.png
lolly look poster.svg --region=0,0,400,300 --grid=20 --output=corner.png
lolly sample poster.svg --points="120,80;640,400" --radius=3
lolly trace photo.jpg --max-lines=20 --design-layers --jsonlookdraws the picture, or one region enlarged, with a grid numbered in the picture's own units: the SVG's viewBox (for Lolly Design, the artboard pixels a layer's x, y, w and h use) or a raster's pixels. With--jsonit needs--output, because the picture and the envelope cannot share stdout.samplegives the colour at each point, averaged over a small disc, with the nearest colour of the active design system and its distance (ΔE in OKLab).tracegives the picture's edges as lines in the same units, longest first;--design-layersadds each line as a Lolly Design path layer.
Where saved sessions live
State a tool saves during a lolly run stays in memory for that run. The run does read the saved sessions this machine already has. One directory serves the desktop app, the TUI and the CLI, picked in this order:
$LOLLY_STATE_DIR, when you name one.$LOLLY_TUI_DIR, the old name for the same thing. It still works and prints a one-line note naming its replacement.- The desktop app's data directory, when the app is installed:
~/Library/Application Support/tools.lolly.Desktopon macOS,$XDG_DATA_HOME/tools.lolly.Desktop(or~/.local/share/...) on Linux,%APPDATA%\tools.lolly.Desktopon Windows. ~/.lolly.
Sessions are in saved-state/<slot>.json in that directory, in the record the desktop app writes. A project saved in the app loads in the terminal by its slot, and one saved in the TUI opens in the app.
lolly writes a tool's saved state to disk only when step 1 or 2 sets the directory. A headless render then leaves no unrequested files in your home directory or the app's store. Name a directory to make a state-saving tool scriptable across runs.
Terminal design systems are kept differently. lolly system init, import, add and use store them under design-systems/, with the list in design-systems.json, in the directory the order above picks. A bare lolly in a terminal also records there that you have seen its start screen.
Publish a brand page
Brand pages explains what a page is for, what goes public and how to read someone else's page.
lolly system publish --out=<dir> writes one folder that works as a press kit and an agent kit: index.html with its markdown twin index.md, brand.json, DESIGN.md, AGENTS.md, llms.txt, checks.json, tokens per colourway and mode, and the logos, fonts, public brand skills and examples that may go public. Nothing leaves your machine. You read the folder and host the folder where you choose.
The source is --file=<tokens>, then a content profile you name with --profile=<name> or LOLLY_PROFILE, then the active terminal system. A profile is never published by default, and a pack marked as managed also needs --manager-allows.
Every lolly system publish flag
| Flag | What it does |
|---|---|
--out=<dir> | The folder to write. It must be new or empty. |
--origin=<url> | The address the folder will be served from, recorded in brand.json. |
--usage-file=<file> | The publisher's own words. A text file is the usage statement. A JSON file may hold statement, contact, url and fonts, where each family gives a url and licence. |
--include=<id,id> | Logos to publish although no licence is recorded for them: your stated choice. |
--no-examples | Leave out the drawn examples. |
--no-made-with-link | Leave out the "Made with Lolly" link in the page's footer. It is on by default. |
--record-address | After writing the folder, record --origin on the active terminal design system, so its exports name the page. Needs a plain https address on a named host. Off by default. Turn this on once the page is live there. |
--no-record-address | Remove that setting from the active terminal design system. |
--name=<name>, --id=<id> | Override the name and the id. |
What is held back. A logo with no recorded licence stays out unless you name the logo with --include. A logo whose rights record says own-work, with its owner and terms, travels as "Owner-published, not an open licence" (Publish your own marks). A font file needs a recorded licence that allows passing the file on; --include does not change this rule. The page gives the name of the face and draws its specimen as vector outlines. Internal brand skills never appear. The command, brand.json and the page each list what was held back and why.
What is checked. checks.json holds contrast measurements of the colour pairs in every colourway and mode, and house rule checks on example documents. They do not judge a finished piece.
The same input gives the same bytes, so you can build twice and compare the folders.
Shell completion (lolly completion)
lolly completion bash|zsh|fish prints a completion script for verbs, flags and the tool ids in the active profile's catalog:
lolly completion bash > /usr/local/etc/bash_completion.d/lolly # Homebrew bash-completion
lolly completion zsh > ~/.zsh/completions/_lolly # then: autoload -U compinit && compinit
lolly completion fish > ~/.config/fish/completions/lolly.fishThe list is taken when the script is generated, so run lolly completion <shell> again after installing new tools.