CLI reference
Every open-assets command with its arguments, global flags, exit codes and how the optional dir argument picks the project folder that holds assets.json.
The open-assets binary ships in the @open-assets/open-assets package. It needs Node 18 or newer.
npm install --save-dev @open-assets/open-assetsRun it with npx open-assets <command>, or through a package script.
Commands
| Command | What it does |
|---|---|
open-assets dev | Start the dev server with live preview and export UI |
open-assets render | Render assets headlessly via CLI |
open-assets list | List all collections and templates defined in the config |
open-assets validate | Validate the assets.json and check that all referenced files exist |
open-assets init | Scaffold a new assets.json and example assets |
open-assets add collection | Add a new asset collection (choose from presets or custom) |
open-assets add template | Add a new template to an existing collection (HTML or SVG) |
open-assets add size | Add an export size to a collection (choose from presets or custom) |
open-assets skills | Install Claude Code skills for open-assets into the current project |
add is a parent command with three subcommands: add collection, add template and add size. All three are on /reference/cli/add.
Global flags
| Flag | Effect |
|---|---|
-V, --version | Print the installed version (read from the package's package.json) and exit. |
-h, --help | Print help and exit. Works on every command: open-assets render --help, open-assets add size --help. |
There are no other global flags. Every other option belongs to a single command.
The [dir] argument
Every command takes an optional positional [dir]. It defaults to ., the current working directory.
- The CLI resolves
dirto an absolute path and treats it as the project root. - The config file is looked up inside it:
dir/assets.json, ordir/<--config value>. - Template
srcpaths,localizations,publicDir,outFileandxcodepaths in the config resolve against the project root. initandskillstreatdiras the folder to write into.
open-assets validate ./marketing
open-assets render ./marketing --collection screenshotsTwo paths do not resolve against [dir]: render --output and dev --static-dir. Both resolve against the directory you run the command from. open-assets render ./marketing writes to ./exports, not ./marketing/exports. Pass -o ./marketing/exports, or cd into the project first. See /reference/cli/render.
Flag and environment precedence
Several options read an environment variable when the flag is absent. The order is: flag, then environment variable, then the built-in default. The full list is on /reference/env.
Exit codes
| Code | When |
|---|---|
0 | The command finished. This includes a render that skipped every collection because a --size or --locale did not match (it prints a warning, not an error). |
1 | The config file is missing or is not valid JSON; render --collection or --tag matched nothing; list --tag matched nothing; validate found at least one error; add hit a duplicate id or name; init found an existing assets.json; dev could not find a free port after 10 retries. |
| non-zero | An uncaught exception, such as a template that fails to load within the render timeout or a localizations file that is missing at render time. Node prints the stack trace. |
Each command page lists its own exit behavior.
Command pages
dev
Preview server with live reload and export menu
render
Headless export of every size, locale and output
list
Print collections, templates and sizes
validate
Check the config and that template files exist
init
Scaffold assets.json and starter templates
add
Add a collection, template or export size
skills
Copy the Claude Code skill into a project
Last updated on
Other CI and Docker
Run Open Assets in GitLab CI, CircleCI or a Docker image: install Chromium dependencies for Puppeteer, render headlessly, and use validate as a required check.
open-assets dev
Start the Open Assets preview server with live reload, a locale picker and an export menu, plus its HTTP endpoints, static folders and every option it accepts.