> ## Documentation Index
> Fetch the complete documentation index at: https://www.nexrender.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Workflows

> Let Claude Code, Codex, and other coding agents operate Nexrender Cloud through the Nexrender CLI

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](https://github.com/nexrender/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

> [tab] macOS, Linux, and WSL
>
> ```bash theme={null}
> curl -fsSL https://raw.githubusercontent.com/nexrender/nexrender-cli/main/scripts/install.sh | sh
> ```

> [tab] Windows
>
> ```powershell theme={null}
> irm https://raw.githubusercontent.com/nexrender/nexrender-cli/main/scripts/install.ps1 | iex
> ```

> [tab] Go
>
> ```bash theme={null}
> go install github.com/nexrender/nexrender-cli/cmd/nexrender@latest
> ```

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

## Connect your account and your agent

Run setup:

```bash theme={null}
nexrender setup
```

Setup does two things:

1. If no API token is saved yet, it asks for one. Create a token on the [API tokens](https://app.nexrender.com/settings/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:

```bash theme={null}
nexrender auth status
nexrender team show
```

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:

```bash theme={null}
export NEXRENDER_API_KEY="..."
nexrender auth status
```

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

```bash theme={null}
nexrender template upload intro.aep --name "Intro"
```

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

**2. Read its compositions and layers**

```bash theme={null}
nexrender template compositions TEMPLATE_ID --json
nexrender template layers TEMPLATE_ID --json
```

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](https://www.nexrender.com/docs/cloud/templates/inspecting.md) for every field.

**3. Write the job**

Use the exact names from the previous step:

```json job.json theme={null}
{
  "template": {
    "id": "TEMPLATE_ID",
    "composition": "main"
  },
  "assets": [
    {
      "type": "data",
      "layerName": "title",
      "property": "Source Text",
      "value": "Summer sale"
    }
  ]
}
```

For every job field, see [Initiating Renders](https://www.nexrender.com/docs/cloud/jobs/initiating_renders.md).

**4. Check it, then render**

```bash theme={null}
nexrender job submit --file job.json --dry-run
nexrender job submit --file job.json --wait --json
```

`--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**

```bash theme={null}
nexrender job diagnose JOB_ID
nexrender job logs JOB_ID
```

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

```bash theme={null}
nexrender skill install --agent claude
```

| Agent | `--agent` value | Skill folder |
| - | - | - |
| Claude Code | `claude` | `~/.claude/skills/nexrender` |
| Codex | `codex` | `~/.codex/skills/nexrender` |
| Other agents that load skills from `~/.agents/skills` | `agents` | `~/.agents/skills/nexrender` |

Setup never installs to `~/.agents/skills` on its own. Pass `--agent agents` to install it there, or `--agent all` for all three folders.

> [!NOTE]
>
> The CLI does not overwrite a skill folder that it did not create. If you installed the standalone [nexrender-skill](https://github.com/nexrender/nexrender-skill) in one of these folders, replace it with the CLI's skill:
>
> ```bash theme={null}
> nexrender skill install --agent claude --replace
> ```

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:

```bash theme={null}
nexrender skill print
```

This prints only the main skill file. Its reference pages on payload rules and direct API calls stay in the [CLI repository](https://github.com/nexrender/nexrender-cli/tree/main/skills/nexrender/references).

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

```bash theme={null}
nexrender secret set FAL_KEY
```

Then add an `nx:genai` entry to the job's `assets` array and reference the secret by name:

```json theme={null}
{
  "type": "function",
  "name": "nx:genai",
  "params": {
    "provider": "fal",
    "key": "${secrets.FAL_KEY}",
    "model": "fal-ai/flux/schnell",
    "type": "image",
    "layerName": "hero-image",
    "data": {
      "prompt": "Abstract tech landscape, purple tones, dark background"
    }
  }
}
```

Nexrender passes the `data` object to the fal.ai model unchanged, so its shape depends on the model. See the [fal.ai model library](https://fal.ai/models) 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](https://www.nexrender.com/docs/cloud/jobs/functions/nx-gen-ai.md#video-length).

See [`nx:genai`](https://www.nexrender.com/docs/cloud/jobs/functions/nx-gen-ai) for every parameter and [Secrets Management](https://www.nexrender.com/docs/cloud/jobs/secrets.md) 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:

```bash theme={null}
nexrender batch submit --file campaign.json --dry-run
nexrender batch submit --file campaign.json
nexrender batch wait BATCH_ID
```

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](https://www.nexrender.com/docs/cloud/jobs/batch_jobs.md#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:

```json theme={null}
{
  "webhook": {
    "url": "https://yourdomain.com/webhooks/render-complete"
  }
}
```

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](https://www.nexrender.com/docs/cloud/jobs/tracking_renders.md) 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](https://github.com/nexrender/nexrender-skill). It describes the REST API, job payloads, asset types, codecs, secrets, and fonts, so the agent can call the API directly.

## Related

* [Nexrender CLI on GitHub →](https://github.com/nexrender/nexrender-cli)
* [Template Introspection →](https://www.nexrender.com/docs/cloud/templates/inspecting.md)
* [Initiating Renders →](https://www.nexrender.com/docs/cloud/jobs/initiating_renders.md)
* [AI Content Generation (nx:genai) →](https://www.nexrender.com/docs/cloud/jobs/functions/nx-gen-ai.md)
* [Batch Jobs →](https://www.nexrender.com/docs/cloud/jobs/batch_jobs.md)
* [Secrets Management →](https://www.nexrender.com/docs/cloud/jobs/secrets.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.