@genart-dev/cli

Command-line interface for genart.dev — render, batch, montage, import, validate, export, and scaffold generative art sketches. Includes a built-in MCP server for AI agent integration.

Part of genart.dev — a generative art platform with an MCP server, desktop app, and IDE extensions.

Install

npm install -g @genart-dev/cli

Quick Start

# Create a new sketch
genart init "spiral grid" --renderer p5

# Render to PNG
genart render spiral-grid.genart -o spiral-grid.png

# Batch render with seed sweep
genart batch spiral-grid.genart --seeds 1-20 --concurrency 8

# Export standalone HTML
genart export spiral-grid.genart --format html

# Import existing source code
genart import sketch.js

# Record a video
genart video spiral-grid.genart --duration 10 --fps 30

# Connect your AI agent
genart agent install claude

Commands

genart render <file>

Render a .genart sketch to an image.

genart render sketch.genart
genart render sketch.genart -o output.png --wait 1s --scale 2
genart render sketch.genart --seed 42 --preset landscape-1000
genart render sketch.genart --params '{"amplitude": 0.8}' --colors '["#ff0000", "#00ff00"]'

Option	Default	Description
--wait <duration>	500ms	Wait time before capture
--seed <n>		Override seed
--params <json>		Override parameters (JSON object)
--colors <json>		Override color palette (JSON array)
--width <n>		Override canvas width
--height <n>		Override canvas height
--preset <name>		Canvas preset (e.g. square-600, landscape-1000)
--format <fmt>	png	Output format: png, jpeg, webp
--quality <n>	80	Lossy compression quality (0–100)
--scale <n>	1	Pixel density multiplier
-o, --output <path>		Output file path

genart info <files...>

Inspect .genart sketch metadata — title, renderer, canvas, parameters, colors, skills, dates.

genart info sketch.genart
genart info *.genart --json
genart info sketches/ --table

Option	Description
--json	Machine-readable JSON output
--table	Tabular output for multiple files

genart validate <paths...>

Validate .genart files. Accepts files and directories (scans recursively).

genart validate sketch.genart
genart validate ./sketches/ --strict

Option	Description
--strict	Also run renderer-specific validate() on algorithm source

genart init [name]

Scaffold a new .genart sketch file with interactive prompts.

genart init
genart init "wave field" --renderer three --preset portrait-800

Option	Default	Description
--renderer <type>	(interactive)	p5, canvas2d, three, glsl, svg
--preset <name>	square-600	Canvas preset
--title <string>	(interactive)	Sketch title

genart export <file>

Export sketch as HTML, image, or algorithm source.

genart export sketch.genart --format html -o sketch.html
genart export sketch.genart --format png --scale 2
genart export sketch.genart --format algorithm   # extracts .js or .glsl

Option	Default	Description
--format <fmt>	html	html, png, jpeg, webp, algorithm
--wait <duration>	500ms	Render wait time (image formats)
--seed <n>		Override seed
--params <json>		Override parameters
--colors <json>		Override color palette
--width <n>		Override canvas width
--height <n>		Override canvas height
--preset <name>		Canvas preset
--quality <n>	80	Lossy compression quality (0–100)
--scale <n>	1	Pixel density multiplier
-o, --output <path>		Output file path

genart batch <files...>

Generate many renders from one sketch — seed ranges, parameter sweeps, random combinations.

genart batch sketch.genart --seeds 1-100 --concurrency 8 -o renders/
genart batch sketch.genart --sweep amplitude=0:1:0.1 --manifest
genart batch sketch.genart --random 50 --naming "{id}-{seed}-{params}"
genart batch sketch.genart --seeds 1-5 --sweep size=10:50:10 --matrix

Option	Default	Description
--seeds <range>		Seed range or list (e.g. 1-100, 1,5,42)
--sweep <spec>		Parameter sweep: key=min:max:step (repeatable)
--random <n>		Generate N random seed + param combinations
--matrix		Cartesian product of seeds × sweeps
--concurrency <n>	4	Parallel captures
--naming <pattern>	{id}-{seed}	Output naming (tokens: {id}, {seed}, {index}, {params})
--manifest		Write manifest.json with per-render metadata
--wait <duration>	500ms	Render wait time
--format <fmt>	png	png, jpeg, webp
--quality <n>	80	Lossy compression quality (0–100)
--scale <n>	1	Pixel density multiplier
--width <n>		Override canvas width
--height <n>		Override canvas height
--preset <name>		Canvas preset
--colors <json>		Override color palette
-o, --output-dir <dir>	.	Output directory

genart montage <source>

Compose a grid of images into a single montage. Reads from a directory or manifest JSON on stdin.

genart montage renders/ -o grid.png --columns 10 --gap 4
genart batch sketch.genart --seeds 1-25 --manifest | genart montage - --label seed

Option	Default	Description
--columns <n>	(auto)	Grid columns
--rows <n>	(auto)	Grid rows
--tile-size <WxH>		Force tile dimensions (e.g. 200x200)
--gap <px>	2	Gap between tiles
--padding <px>	0	Outer padding
--background <hex>	#0A0A0A	Background color
--label <mode>	none	Label tiles: seed, params, filename, index, none
--label-color <hex>	#999999	Label text color
--label-font-size <px>	11	Label font size
--sort <key>		Sort: seed, name, param:<key>
-o, --output <path>	montage.png	Output file

Requires sharp — install with npm install sharp.

genart import <files...>

Convert source files (.js, .glsl) into .genart sketches. Auto-detects renderer, parameters, colors, and canvas size from source code.

genart import sketch.js
genart import *.js --batch --renderer p5 --title "My Series"
genart import shader.glsl --preset landscape-1000 --seed 42
genart import sketch.js --dry-run

Option	Default	Description
--renderer <type>	(auto-detect)	Force renderer type
--preset <name>	square-600	Canvas preset
--title <string>	(interactive)	Sketch title
--seed <n>		Initial seed
-y, --non-interactive		Accept all defaults
--batch		Process multiple files non-interactively
--dry-run		Preview without writing
-o, --output <path>		Output path (single file only)

Renderer auto-detection analyzes source code for framework-specific patterns (p5 instance methods, Canvas2D API, THREE constructors, GLSL builtins, SVG namespaces) and reports confidence level (high, medium, low).

genart video <file>

Render a video from an animated sketch. Captures frames via headless Chrome and encodes with ffmpeg.

genart video sketch.genart --duration 10
genart video sketch.genart --duration 5 --fps 60 --format webm --codec vp9
genart video sketch.genart --duration 3 --animate amplitude=0:1 --easing ease-in-out
genart video sketch.genart --duration 2 --format gif --loop 0

Option	Default	Description
--duration <seconds>	(required)	Video duration in seconds
--fps <n>	30	Frames per second
--format <fmt>	mp4	mp4, webm, gif
--codec <name>	h264	h264, h265, vp9
--quality <n>	75	Encoding quality (0–100)
--animate <spec>		Interpolate parameter: param=start:end (repeatable)
--easing <fn>	linear	linear, ease-in, ease-out, ease-in-out
--loop <n>	0	GIF loop count (0 = infinite)
--concurrency <n>	4	Parallel frame captures
--wait <duration>	200ms	Init wait before time injection
--seed <n>		Override seed
--params <json>		Override parameters
--colors <json>		Override color palette
--width <n>		Override canvas width
--height <n>		Override canvas height
--preset <name>		Canvas preset
-o, --output <path>		Output file path

Requires ffmpeg in PATH.

genart agent <subcommand>

MCP server and AI agent configuration. See Agent Integration below.

Agent Integration

The CLI includes a built-in MCP server with 33 tools for creating and manipulating generative art. Connect it to any AI coding agent.

genart agent install [client]

Configure MCP for an AI client with one command.

genart agent install claude
genart agent install cursor
genart agent install --all          # configure all detected clients
genart agent install claude --npx   # use npx instead of global binary
genart agent install --remove       # remove genart from all clients
genart agent install vscode --dry-run

Option	Description
--all	Configure all clients whose binary is detected in PATH
--remove	Remove genart MCP configuration
--dry-run	Preview changes without writing
--npx	Force npx invocation (npx -y @genart-dev/cli agent stdio)

Supported AI Clients

Client	ID	Config Path (macOS)	Binary
Claude Code	claude	~/.claude.json	claude
Codex CLI	codex	~/.codex/config.toml	codex
Cursor	cursor	~/.cursor/mcp.json	cursor
VS Code	vscode	~/Library/Application Support/Code/User/settings.json	code
Gemini CLI	gemini	~/.gemini/settings.json	gemini
OpenCode	opencode	~/.config/opencode/opencode.json	opencode
Kiro	kiro	~/.kiro/settings/mcp.json	kiro
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json	windsurf

genart agent stdio

Start MCP server over stdio transport. This is what AI clients connect to.

genart agent stdio
genart agent stdio --base-path ~/sketches

Option	Default	Description
--base-path <dir>	cwd	Base directory for file operations

genart agent http

Start MCP server over HTTP (Streamable HTTP transport) for browser or network access.

genart agent http
genart agent http --port 8080 --cors

Option	Default	Description
--port <n>	3333	Port to listen on
--host <addr>	127.0.0.1	Host to bind to
--base-path <dir>	cwd	Base directory for file operations
--cors		Enable CORS headers

genart agent sidecar

Start MCP server in sidecar mode (stdio + IPC mutations). Used by the Electron desktop app for real-time UI updates.

genart agent sidecar --base-path ~/project

Option	Default	Description
--base-path <dir>	cwd	Base directory for file operations

genart agent doctor

Diagnose your genart MCP setup — checks CLI version, Chrome, ffmpeg, sharp, and per-client configuration.

genart agent doctor

Hybrid Workflow

The CLI and MCP server are designed to work together. Your AI agent creates and edits sketches through the MCP tools, then you use the CLI to render, batch, export, and compose:

# 1. Connect your agent
genart agent install claude

# 2. Ask the agent to create sketches
#    "Create a workspace with three p5.js sketches exploring Perlin noise"

# 3. Render the results
genart render noise-field.genart -o noise-field.png

# 4. Explore the parameter space
genart batch noise-field.genart --seeds 1-100 --sweep scale=0.01:0.1:0.01 --matrix

# 5. Compose a montage
genart montage renders/ --columns 10 --label seed -o exploration.png

# 6. Record a video
genart video noise-field.genart --duration 10 --animate scale=0.01:0.1 --easing ease-in-out

Environment Variables

Variable	Description
GENART_CHROME_PATH	Override Chrome/Chromium path for headless rendering. Auto-detected by default.

Optional Dependencies

Package	Required For	Install
sharp	montage command	npm install sharp
ffmpeg	video command	brew install ffmpeg / download
Chrome/Chromium	render, export, batch, video	Auto-detected or set GENART_CHROME_PATH

Related Packages

Package	Purpose
@genart-dev/format	File format types, parsers, presets
@genart-dev/core	Renderer adapters, skill registry
@genart-dev/mcp-server	MCP server + CLI (33 tools)

Support

Questions, bugs, or feedback — support@genart.dev or open an issue.

License

MIT