lolly CLI: create and process files

Use lolly when you want a Lolly file without opening the app: in a build script, a CI job, a folder of files to process or an agent's tool call. It runs the same engine as the app, so the file matches the one the export panel would make.

From the terminal you can:

• make a file with any tool, giving its inputs as flags;
• find tools, their inputs and the catalog's logos and icons;
• set up your design system for the terminal;
• check, clean or convert files you already have.

Every flag is a URL parameter by another name. --url=https://example.com is ?url=https://example.com in a share link, which is why a link copied from the app renders the same here (URL Mode). To browse with the keyboard instead, run lolly tui (TUI).

Install

There are two routes to the same program.

The desktop app. Lolly for macOS, Windows and Linux carries its own tools, catalog and this CLI, so installing the app is enough. On macOS the command is the app's own executable, Lolly.app/Contents/MacOS/lolly-desktop, with the same arguments. run uses the app's native off-screen WebView; the other verbs go to the bundled Node package.

A checkout. In a clone of the Lolly source (github.com/lolly-tools/lolly) the CLI is a package script.

In a checkout, pnpm run cli takes the place of lolly. Examples on these pages that start with lolly run as pnpm run cli followed by the same arguments.

A standalone CLI carries no tools and no catalog

Tools and brand assets are content, not code, and the public set alone runs to hundreds of megabytes. A standalone lolly (the packaged CLI, see Build the CLI and TUI) carries none of it, so point it at a root:

LOLLY_ROOT=/path/to/lolly lolly list

Two kinds of directory work:

• a checkout of this repository, which holds profiles.json and the packs under community/ and brands/;
• a materialized root: a tools/ directory of tool folders and a built catalog/ with its generated index, which is what a dist/ build, an RPM payload or a container image carries.

A LOLLY_ROOT that holds neither is ignored, and the CLI falls back to looking upward from itself, then in the working directory. Build any pack's tools/ and catalog/ this way and every command (render, batch, smoke, assets) runs against it with no code change. The desktop app brings its own root, so it needs no pointing.

lolly system import <pack.lolly> is a different thing: it imports your design system, and it adds no tools, so it needs a root as well. Run a command that needs content without any, and the CLI lists these routes and exits 3. It never downloads anything on its own.

Make your first file

lolly qr-code --url=https://example.com --output=qr.svg

The CLI says which design system it recorded in the file, then ends with a line that starts ✓ Wrote:

Recorded the design system: Lolly Starter. Pass --no-madewith to leave the record out.
✓ Wrote 20381 bytes to qr.svg

In a checkout, a note that the catalog is unsigned comes first. That is expected for a local catalog.

qr.svg is written to the current directory, replacing any file of that name. If your own address contains ? or &, put it in quotes.

The general form is lolly <tool-id> [--input=value ...] [--export=fmt] [--output=file]. With --output, the file is written and the byte count goes to stderr. Without it, the bytes go to stdout, so you can pipe them:

pnpm --silent run cli qr-code --url=https://example.com --export=png > qr.png

The --output extension asks for a format, so a tool that cannot write it stops instead of writing other bytes under your name. Render with the CLI explains that check, along with sizes, print options and video.

Find tools, inputs and assets

lolly list                       # every tool: id, status, description
lolly list --json --q=chart --limit=5
lolly describe qr-code           # that tool's inputs, defaults and formats
lolly qr-code                    # the same as describe, when no flags follow
lolly assets                     # every catalog asset id: logos, icons, photos
lolly assets logo                # filter by text
lolly assets --type=raster

describe lists a tool's essential inputs with their defaults and a usage line; --all shows every input. Inputs that are not a plain value (asset, blocks, vector, file, color) get a ↳ line showing how to write one.

list --q=<words> matches tool ids, names, descriptions, categories and formats, and --limit=1..100 keeps an agent's answer short. With --json, either option adds query, limit and total to the result. assets --type= is checked against the catalog, so a typo is an error that lists the real types rather than an empty list:

$ lolly assets --type=rastor
Error: No catalog asset has type "rastor". This catalog has: audio, data, lut, model, palette, raster, tokens, vector.

Any asset id can fill an asset input, and so can a lolly.tools tool URL, which places that tool's render. To write a bare asset straight to a file, use the asset-export tool:

lolly asset-export --src=lolly/logo/primary --export=svg --output=logo.svg
lolly asset-export --src='https://lolly.tools/tool/qr-code.svg?url=x' --output=qr.svg

lolly --help prints every command, flag and exit code, and each document verb has its own help, such as lolly check --help.

Bring your design system

Run lolly on its own in a terminal and it starts here:

Lolly

Start with what you have. Setup is optional, and each source can be added later.

  One colour       lolly system init --color=#7c3aed --name="My system"
  .lolly or tokens lolly system import ./brand.lolly
  More resources   lolly system add ./logo.svg ./font.woff2
  Explore first    lolly list
  Make something   lolly qr-code --url=https://example.com --output=qr.svg

Design-system commands: lolly system status | list | use | import | add | export | inspect | diff | generate | sync

Piped into another program, the same bare lolly lists the tools instead.

A terminal design system is the colours, type and logos every render then uses. Build one from a single colour with system init, or bring one in with system import: a .lolly pack, a tokens file, a Penpot file, a token zip or an SVG. system add keeps fonts, logos and other source material with the system. system status shows which system is active, system use <id> switches and system export writes the active one as a portable .lolly pack.

The CLI and the TUI share one store, so a system set up in one is active in the other. Where saved sessions live says which directory holds the store. Token workflows covers system inspect, diff, generate and sync.

Where to go next

The Batch view in the app (#/batch) is the interactive counterpart to lolly batch: a spreadsheet grid with CSV round-trip and per-row output.

Every command

The first argument is either a verb or a tool id, and verbs win. lolly run <tool-id> and lolly describe <tool-id> are the unambiguous spellings; a bare lolly <tool-id> renders when flags follow and describes when none do. A pasted lolly.tools link can be the first argument too (Run a share link).