CLI

Command-line client for the Render API — render, wait, status, download, batch, and inspect template schemas.

The j2i CLI lets you create renders, wait for jobs, download assets, mint signed URLs, and inspect template schemas from your terminal or CI pipelines.

For TypeScript apps, use the Node.js SDK. For raw HTTP endpoints, see the API reference.

Install

npm install -g @j2i/cli

Or run without installing:

npx @j2i/cli --help

The binary name is j2i. From this repo: bun run j2i -- --help.

Auth and global options

Create an API key in the dashboard, then set it in your environment. See Authentication.

export JSONTOIMG_API_KEY=sk_...

Flag	Environment variables	Meaning
`--api-key <key>`	`JSONTOIMG_API_KEY`, `RENDER_API_KEY`	API key (required)
`--base <url>`	`JSONTOIMG_API_URL`, `RENDER_BASE_URL`	API origin (default `https://app.jsontoimg.com`)
`--json`	—	Machine-readable errors (JSON on stderr)
`-h`, `--help`	—	Show help

j2i schema <template-id>

Commands

Command	Purpose
`render`	Create a render (optionally wait and download)
`wait <id>`	Wait for a render to finish
`status <id>`	Get current render job status
`download <id>`	Download the render asset
`batch`	Create a batch from a JSON file
`batch-status <id>`	Get batch status
`sign`	Mint a signed CMS / OG image URL
`sign-batch`	Mint up to 50 signed URLs
`schema <templateId>`	Get template layer schema
`templates`	List templates

`render`

Creates a render. By default waits up to 60 seconds. Use --async to return as soon as the job is queued.

Flag	Required?	Notes
`--payload <file>`	one of payload/template	Full create-render JSON
`--template <id>`	one of payload/template	Minimal body with only the template ID
`--format <fmt>`	no	`png` \| `jpg` \| `webp` \| `pdf` \| `avif`
`--wait <sec>`	no	Block until done (default `60`)
`--async`	no	Return without waiting
`--out <file>`	no	Save the asset when the job is `done`

j2i render --payload ./job.json --out ./out.png

j2i render --template <template-id> --format png --wait 90

j2i render --payload ./job.json --async

`wait`

j2i wait <render-id>
j2i wait <render-id> --timeout 60

Blocks until the render finishes (or the timeout). See SSE and wait.

`status`

j2i status <render-id>

Fetches the current job without waiting. Same JSON as GET /api/v1/renders/{id}.

`download`

j2i download <render-id> --out ./out.png

--out defaults to <id>.bin. Prints { id, out, bytes, contentType } as JSON. The job must be done.

`batch`

j2i batch --payload ./jobs.json

--payload is required and must be { "jobs": [ ... ] }. Up to 50 jobs per batch. See Batch renders.

`batch-status`

j2i batch-status <batch-id>

`sign`

j2i sign --payload ./sign.json

--payload is required. Same JSON as signImageUrl (template, optional layers, variables, expiresIn). See URL rendering.

`sign-batch`

j2i sign-batch --payload ./sign-jobs.json

--payload is required and must be { "jobs": [ ... ] }. Up to 50 URLs. Does not queue renders — use batch for that.

`schema`

j2i schema <template-id>
j2i schema <template-id> --version 1

Lists named layers you can override in layers.

`templates`

j2i templates
j2i templates --project <project-id>
j2i templates --limit 50 --offset 0

Lists templates with names and descriptions so you can pick one before calling schema. Default page size is 50 (max 100).

Payload examples

Single render (--payload for render):

{
  "template": "<template-id>",
  "version": 1,
  "format": "png",
  "scale": 1,
  "transparent": false,
  "layers": {
    "headline": { "text": "Hello" }
  },
  "variables": { "plan": "pro" },
  "webhookUrl": "https://example.com/hook"
}

Batch (--payload for batch):

{
  "jobs": [
    {
      "template": "<template-id>",
      "format": "png",
      "layers": { "headline": { "text": "A" } }
    },
    {
      "template": "<template-id>",
      "format": "jpg",
      "layers": { "headline": { "text": "B" } }
    }
  ]
}

Output

Success responses are pretty-printed JSON on stdout.
With --out on render, a short Wrote … note goes to stderr (omitted when --json is set).
API failures print Error <status>: <message> on stderr, or { error, code, status, details } when --json is set. Exit code is 1.

j2i render --payload ./job.json --json

Node.js SDK — same API in TypeScript
MCP — drive renders from Cursor, Claude, and VS Code
Batch renders
SSE and wait
URL rendering
API reference

On this page