Lolly
ऐप खोलें
  1. ऑटोमेट करें
  2. URL और CLI ऑटोमेशन

CLI reference

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.

CodeNameMeaningWhat to do
0OKThe requested thing was produced.Carry on.
1FAILEDIt 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.
2USAGEWrong 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.
3UNAVAILABLE_HEREImpossible 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.
4REFUSEDA protective check this shell ran said no.Read the findings; do not ship the file as it is.
5NOT_FOUNDA 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.
6AUTHA missing or wrong password or passphrase.Supply the secret.
70INTERNALAn 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;
  • --strict promoted a gate-class warning, or --depth=float was asked of an 8-bit render;
  • lolly check found an error, or any warning under --strict (the writing score, verify.writing-score, never counts);
  • lolly package met a Lolly Design document whose pictures have no bytes or are not catalog ids, or an output that already exists;
  • lolly compose refused a spec (with the JSON pointer of the key) or met an output that already exists;
  • lolly intent refused 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);
  • --password on 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 build does the same and lists those blocks in result.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 schema

list --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:

FlagMeaning
--jsonOne JSON envelope on stdout instead of human text (above). Not valid on a render.
--quietSuppress non-error stderr: progress notes, warnings, the byte-count line. Errors still print.
--verboseDiagnostics and stack traces. DEBUG=1 is an alias.
--strictPromote 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, --versionRecognised 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.

VariableEffect
LOLLY_ROOTThe content root to read tools and the catalog from (A standalone CLI).
LOLLY_PROFILEThe content profile: which tool packs and catalog a checkout uses.
LOLLY_STATE_DIRWhere saved sessions and terminal design systems live (below). LOLLY_TUI_DIR is the old name.
LOLLY_RENDERERauto (default), desktop or chromium: which paint renderer to use.
LOLLY_DESKTOP_BIN, LOLLY_RENDER_SERVERAn app executable in an unusual place, or the app's render.json directly.
LOLLY_BROWSER_PATH, LOLLY_BROWSER_CHANNELA browser binary to use, or an installed channel such as chrome, instead of the downloaded Chromium.
PLAYWRIGHT_BROWSERS_PATHWhere lolly install-browser puts Chromium.
LOLLY_WEB_DIST, LOLLY_WEB_BASEA built web shell somewhere else, or the address of one you serve.
LOLLY_EXPORT_IDLE_TIMEOUT, LOLLY_CLI_TIMEOUTSeconds without progress before a Chromium export stops; the desktop renderer's timeout.
LOLLY_TIER_B_DEBUG1 keeps the headless page's logs, like --tier-b-debug.
LOLLY_TRUST_ANCHORExtra 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_PASSWORDA signing identity (Signing from the terminal).
LOLLY_MODELS_DIR, LOLLY_MODELS_BASEWhere on-device models are read from, and the host they are fetched from.
LOLLY_ORT_EP, LOLLY_ORT_THREADSAn accelerated model provider (coreml, cuda), and a thread cap per model session.
LOLLY_HOOK_WORKER1 runs tool hooks in a worker thread.
SOURCE_DATE_EPOCHThe time written into .lolly zip entries by lolly package.
NO_COLORPlain 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 pinned

The 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 pinned

Both 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
FlagMeaning
--jsonThe 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.
--deepAlso 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-anchorsTrust 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.
--metadataAlso 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:

lolly validate ./contract.pdf --metadata
lolly validate ./photo.jpg --metadata --require=none    # report only, never a gate
--metadata--deep
ReadsEmbedded fields, PDF structure, hidden textPixel watermarks: TrustMark, Content Seal, the Lolly durable mark
NeedsNothing extraThe headless Chromium and a built web shell
Changes the exit codeUnder --strict: hidden text, a GPS fix or bytes after the container exit 4Never
नोट: What this report does not check
  • 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.lolly

compile 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-intent

With --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.

नोट: Not run against a live account

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 --json

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:

  1. $LOLLY_STATE_DIR, when you name one.
  2. $LOLLY_TUI_DIR, the old name for the same thing. It still works and prints a one-line note naming its replacement.
  3. The desktop app's data directory, when the app is installed: ~/Library/Application Support/tools.lolly.Desktop on macOS, $XDG_DATA_HOME/tools.lolly.Desktop (or ~/.local/share/...) on Linux, %APPDATA%\tools.lolly.Desktop on Windows.
  4. ~/.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
FlagWhat 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-examplesLeave out the drawn examples.
--no-made-with-linkLeave out the "Made with Lolly" link in the page's footer. It is on by default.
--record-addressAfter 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-addressRemove 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.fish
नोट: The tool list is a snapshot

The list is taken when the script is generated, so run lolly completion <shell> again after installing new tools.

Section links from the earlier guide