@nexart/cli v0.2.3

Command-line interface for NexArt CodeMode — run, replay, and verify deterministic generative art.

Installation

``bash


Global install (recommended)

npm install -g @nexart/cli

After global install, use the nexart command directly:


nexart run sketch.js --seed 12345
`

Quickstart: Run an Example

The SDK includes example sketches in the examples/ folder:

`bash


1. Set up authentication

export NEXART_RENDERER_ENDPOINT=https://nexart-canonical-renderer-production.up.railway.app
export NEXART_API_KEY=nx_live_your_key_here

2. Run the main example sketch (outputs to current directory)

npx @nexart/cli run ./examples/sketch.js --seed 12345 --include-code --out ./out.png

Creates: ./out.png and ./out.snapshot.json

3. Verify the output is deterministic

npx @nexart/cli verify ./out.snapshot.json

Output: [nexart] Result: PASS

`

$3

When you run with --out ./out.png, the CLI creates:
- ./out.png — The rendered PNG image
- ./out.snapshot.json — Snapshot for replay/verify

$3

| File | Description |
|------|-------------|
| examples/sketch.js | Main example — VAR controls + random palette, protocol-safe |
| examples/sketch-minimal.js | Simple shapes, no randomness — identical output every run |
| examples/sketch-vars.js | Uses VAR + random() — demonstrates determinism with same seed |

Canonical Size

The canonical renderer enforces a fixed canvas size:

| Property | Value |
|----------|-------|
| Width | 1950 |
| Height | 2400 |

Important: Do not pass custom --width or --height to the canonical renderer endpoint. The canonical size is enforced server-side for consistent, verifiable output.

`bash


Correct: use default canonical size

nexart run sketch.js --seed 12345

Avoid: custom sizes may be rejected by canonical renderer

nexart run sketch.js --width 800 --height 600 # NOT recommended

`

Quick Start (npx)

Run without installing globally:

`bash


Using npx (no install required)


npx @nexart/cli run sketch.js --seed 12345
npx @nexart/cli verify out.snapshot.json
npx @nexart/cli replay out.snapshot.json --out replay.png
`

Overview

The CLI renders Code Mode sketches via a remote canonical renderer and creates verifiable snapshots.

v0.2.2 features:
- Authenticated remote rendering with API keys
- Real PNG output via remote renderer
- Snapshot v1 format with SHA-256 hashing
- Verify and replay commands
- Optional code embedding in snapshots

Authentication

Remote rendering requires an API key for metered access.

$3

`bash


Set environment variables

export NEXART_RENDERER_ENDPOINT=https://nexart-canonical-renderer-production.up.railway.app
export NEXART_API_KEY=nx_live_your_key_here

Run with authentication

npx @nexart/cli@0.2.2 run sketch.js --seed 12345 --include-code --out out.png
`

$3

`bash


Via environment variable (recommended)

export NEXART_API_KEY=nx_live_...
nexart run sketch.js --seed 12345

Via CLI flag

nexart run sketch.js --seed 12345 --api-key nx_live_...
`

$3

If authentication fails:
`
[nexart] Error: Missing API key for remote rendering.
[nexart] Set NEXART_API_KEY environment variable or pass --api-key.
[nexart] Get your API key at: https://nexart.art/dashboard/api
`

Commands

$3

Execute a sketch and create a snapshot:

`bash


With remote renderer (default, requires API key for remote endpoints)

nexart run sketch.js --seed 12345 --out render.png

With code embedded for standalone verify/replay

nexart run sketch.js --seed 12345 --include-code

Local mode (placeholder PNG, no auth required)

nexart run sketch.js --renderer local
`

Options:
| Flag | Default | Description |
|------|---------|-------------|
| --out, -o | out.png | Output PNG path |
| --seed, -s | random | PRNG seed |
| --vars, -v | 0,0,0,0,0,0,0,0,0,0 | VAR values (comma-separated) |
| --width, -w | 1950 | Canvas width (use default for canonical) |
| --height | 2400 | Canvas height (use default for canonical) |
| --renderer | remote | remote or local |
| --endpoint | env/localhost:5000 | Remote renderer URL |
| --api-key | env | API key for authentication |
| --include-code | false | Embed code in snapshot |
| --runtime-hash | auto | Override runtime hash |

Outputs:
- render.png — The rendered image
- render.snapshot.json — Snapshot for replay/verify

$3

Check that a snapshot produces the expected output:

`bash
nexart verify render.snapshot.json

With external code file


nexart verify render.snapshot.json --code sketch.js
`

Exit codes:
- 0 — PASS (hashes match)
- 1 — FAIL (hashes differ or error)

$3

Re-execute from a snapshot:

`bash
nexart replay render.snapshot.json --out replay.png

With external code file


nexart replay render.snapshot.json --code sketch.js --out replay.png
`

Remote Renderer

The CLI calls a canonical Node.js renderer endpoint for real PNG generation.

$3

`bash


Via environment variable

export NEXART_RENDERER_ENDPOINT=https://nexart-canonical-renderer-production.up.railway.app
export NEXART_API_KEY=nx_live_...

Via CLI flags

nexart run sketch.js --endpoint https://render.nexart.io --api-key nx_live_...
`

$3

`
POST /api/render
Content-Type: application/json
Authorization: Bearer

{
"code": "...",
"seed": 12345,
"VAR": [0,0,0,0,0,0,0,0,0,0],
"width": 1950,
"height": 2400,
"protocolVersion": "1.2.0"
}

Response: image/png (binary)
Headers:
X-Runtime-Hash:
`

$3

`bash
curl -X POST https://nexart-canonical-renderer-production.up.railway.app/api/render \
-H "Content-Type: application/json" \
-H "Authorization: Bearer nx_live_..." \
-d '{"code":"createCanvas(1950,2400);\nbackground(0);\n","seed":12345,"VAR":[0,0,0,0,0,0,0,0,0,0],"width":1950,"height":2400,"protocolVersion":"1.2.0"}' \
--output render.png
`

Snapshot Format (v1)

`json
{
"protocol": "nexart",
"protocolVersion": "1.2.0",
"runtime": "canonical",
"runtimeHash": "",
"codeHash": "",
"seed": 12345,
"VAR": [0,0,0,0,0,0,0,0,0,0],
"canvas": { "width": 1950, "height": 2400 },
"outputHash": "",
"createdAt": "2026-01-25T...",
"code": "..." // optional, if --include-code
}
`

Hash definitions:
- outputHash = SHA-256 of PNG bytes
- codeHash = SHA-256 of normalized code
- runtimeHash = From renderer or SHA-256 of SDK version

Renderer Modes

| Mode | Description |
|------|-------------|
| --renderer remote | Default. Calls canonical renderer with auth, produces real PNG output. |
| --renderer local | NOT implemented yet. Outputs a 1x1 placeholder image only. No auth required. |

`bash


Remote (default) — real PNG output, requires API key for remote endpoints

nexart run sketch.js --seed 12345

Local — NOT implemented, placeholder only, no auth

nexart run sketch.js --renderer local
`

Real local/offline rendering is planned for a future release.

Environment Variables

| Variable | Description |
|----------|-------------|
| NEXART_RENDERER_ENDPOINT | Remote renderer URL (default: http://localhost:5000) |
| NEXART_API_KEY` | API key for authenticated rendering |

License

MIT — Free for all use including commercial.

See Core vs Edges for the NexArt business model.