@nexart/cli v0.2.3

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

Installation

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

# 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

Output Files

When you run with --out ./out.png, the CLI creates:

• ./out.png — The rendered PNG image
• ./out.snapshot.json — Snapshot for replay/verify

Example Sketches

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

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

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

Setup

# 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/[email protected] run sketch.js --seed 12345 --include-code --out out.png

API Key Options

# 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_...

Error Messages

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

Run

Execute a sketch and create a snapshot:

# 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

Verify

Check that a snapshot produces the expected output:

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)

Replay

Re-execute from a snapshot:

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.

Endpoint Configuration

# 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_...

Expected API

POST /api/render
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "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: <hash>

Equivalent curl

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)

{
  "protocol": "nexart",
  "protocolVersion": "1.2.0",
  "runtime": "canonical",
  "runtimeHash": "<sha256>",
  "codeHash": "<sha256>",
  "seed": 12345,
  "VAR": [0,0,0,0,0,0,0,0,0,0],
  "canvas": { "width": 1950, "height": 2400 },
  "outputHash": "<sha256>",
  "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. |

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