Skip to main content
A coding agent such as Claude Code or Codex can work with Nexrender Cloud for you. It can upload a template and list its compositions and layers. It can build a job from those names, render it, and tell you why a render failed. The agent does this with the Nexrender CLI. The CLI stores your API key, so the agent never needs to see it. It gives the agent JSON output, checks payloads locally before you spend render time, and asks for confirmation before it deletes or cancels anything. The CLI also installs a skill that teaches your agent how to use these commands.

​
Install the CLI

If the installer says its folder is not on your PATH, add it before you continue.

​
Connect your account and your agent

Run setup:
Setup does two things:
  1. If no API token is saved yet, it asks for one. Create a token on the API tokens page of the dashboard and paste it in. Setup checks the token and saves it in your system keyring when one is available. If a token is already saved, setup checks that it still works and asks for a new one if it doesn’t.
  2. It installs the Nexrender skill for Claude Code and Codex if it finds them on your computer. It looks for each agent’s settings folder or its command on your PATH.
When you run the installer in a terminal, it starts setup for you. Running setup again is safe, and it installs the skill for any agent you have added since. To use a different API token, run nexrender auth login. Check that the CLI is connected to the team you expect:
If something is wrong, nexrender doctor checks your local configuration and API access.

​
Sandboxes and CI

Some agents run in a sandbox that cannot read your system keyring. Give them the token in the NEXRENDER_API_KEY environment variable instead:

​
Ask for the result you want

Once the skill is installed, describe the outcome. You do not need to name commands:
Upload intro.aep, wait until it is ready, and tell me its compositions and layer names.
Make a job for the main composition that puts “Summer sale” in the title layer. Check it, then render it and send me the output link.
Diagnose job 01JTRDF7HCR8QAHYW8GPCP4S9Y. Do not change or cancel anything.
The skill tells your agent to follow these rules:
  • Check authentication first. If you are not signed in, ask you to run nexrender auth login instead of asking for your token.
  • Listing, inspecting, and diagnosing are fine whenever they help with your request. Submitting, uploading, cancelling, deleting, renaming, or writing a secret needs your clear go-ahead.
  • Run --dry-run before a paid render.
  • Do not resubmit a failed job unless you ask. After a network error on a create, upload, cancel, or delete request, check what happened instead of trying again.
  • Never print tokens or secret values.

​
What the agent runs

You can run the same commands yourself. This is the usual path from a new template to a finished render.
1

Upload the template

The command uploads the file and waits until Nexrender has finished processing it. It prints the template ID.
2

Read its compositions and layers

Composition names go in template.composition. Layer names go in layerName on each asset. Layer names are case-sensitive. Each layer also has a type, size, position, and time range, so an agent can choose the right layer in a template it has not seen before. See Template Introspection for every field.
3

Write the job

Use the exact names from the previous step:
job.json
For every job field, see Initiating Renders.
4

Check it, then render

--dry-run only checks the payload on your computer. The API runs its own checks when you submit, so it can still refuse a payload that passed. --wait follows the job until it finishes or fails. The finished job’s outputUrl links to the rendered file.
5

If the render failed, find out why

diagnose only reads data. It collects the job’s status, error, and render logs. It also reports missing fonts and templates that have not finished processing, and suggests checking layer names when the logs mention a layer.
Commands print a readable summary in a terminal and JSON when you pass --json or pipe the output. To see everything your installed version can do, run nexrender commands --json. For the exact request shape of an API operation, run nexrender schema OPERATION_ID --json, for example nexrender schema createJob --json.

​
Manage the skill

To install the skill for one agent, pass --agent:
Setup never installs to ~/.agents/skills on its own. Pass --agent agents to install it there, or --agent all for all three folders.
The CLI does not overwrite a skill folder that it did not create. If you installed the standalone nexrender-skill in one of these folders, replace it with the CLI’s skill:
Each CLI release includes the version of the skill that matches its commands. To update both, run the installer again. In a terminal, the installer runs setup, which refreshes every copy of the skill that the CLI installed. Without a terminal, for example in CI, it runs nexrender skill update, which refreshes those copies without installing the skill anywhere new. You can run nexrender skill update yourself at any time. If your agent loads instructions some other way, print the skill and add it wherever the agent reads its instructions:
This prints only the main skill file. Its reference pages on payload rules and direct API calls stay in the CLI repository.

​
Generate assets with AI

The nx:genai function asks an AI media provider to create an image, video, or audio file, then places it in a layer before the job renders. The only supported provider right now is fal.ai. If you need another provider, contact support so we can prioritize it. Store your fal.ai key as a Nexrender secret first. The CLI asks for the value without showing it on screen:
Then add an nx:genai entry to the job’s assets array and reference the secret by name:
Nexrender passes the data object to the fal.ai model unchanged, so its shape depends on the model. See the fal.ai model library for models and their inputs. Set type to the kind of file the model returns: image, video, or audio. The file replaces the footage of layerName. Generation runs as a separate job, and your render waits until it finishes. Nexrender does not measure a generated video, so set the layer and composition length yourself. See Video Length. See nx:genai for every parameter and Secrets Management for how secrets work.

​
Render many videos at once

A batch holds up to 1,000 jobs. Each one is an ordinary job payload. Check the file, submit it, and wait for the whole batch:
Jobs that fail validation are listed in the batch’s errors array. The rest of the batch still renders. If a submission times out, you may not know whether the batch was created. To make it safe to send again, give the batch a batchId (a ULID you choose) and give each job a batchItemId. Sending the same file again then creates only the jobs that are missing. Do not send it while the first attempt may still be running: check nexrender batch show BATCH_ID until it stops changing. Retries are recognized for 30 days. See Retry a Batch Safely for the details.

​
Get notified when a render finishes

--wait and nexrender job wait work well while an agent is running. When your agent runs as a service and should react later, add a webhook to the job or batch payload:
When the job finishes or fails, Nexrender sends the job object to this URL in a POST request. Your endpoint must return a 2xx status. If it doesn’t, or the connection fails, Nexrender retries up to 3 times, waiting longer before each try. See Tracking Renders for the payload.

​
Agents that cannot run commands

Some agents, such as hosted chat assistants, cannot run programs on your computer. If such an agent can make authenticated HTTP requests, give it the standalone nexrender-skill. It describes the REST API, job payloads, asset types, codecs, secrets, and fonts, so the agent can call the API directly.