Renoise CLI

Renoise CLI — Agent Workflow

The native renoise binary is the only source of truth for authentication, commands, models, capabilities, defaults, validation, API behavior, uploads, task state, and output formats. Do not maintain model tables or reproduce API logic in this plugin.

Platform URL: https://www.renoise.ai — never renoise.com.

Preflight

Run this at the start of every generation session:

# If this plugin copy is behind the latest GitHub Release, tell the user how to
# update the plugin on their host (exit 2). Continue only after they update, or
# if the check fails open (network) and the CLI path below still works.
node "${CLAUDE_SKILL_DIR}/../renoise-setup/scripts/check-plugin.mjs"
# Keep the managed CLI on the latest public release (no user prompt).
node "${CLAUDE_SKILL_DIR}/../renoise-setup/scripts/install-cli.mjs" --ensure
# Prefer the managed install for this shell (Unix).
export PATH="${HOME}/.local/bin:${PATH}"
command -v renoise >/dev/null 2>&1 || exit 127
renoise version
renoise help task create | grep -q -- '--prompt-file'
renoise help task wait | grep -q 'renoise task wait'
renoise help analyze | grep -q -- '--mode'
renoise help auth exec | grep -q 'renoise auth exec'
renoise auth status --json
renoise model --json

On Windows PowerShell, run the same node ... check-plugin.mjs and node ... install-cli.mjs --ensure, then prepend $env:LOCALAPPDATA\Renoise\bin to $env:Path. Use Get-Command renoise instead of command -v, and confirm task help contains renoise task create plus --prompt-file and renoise task wait, analyze help contains --mode, and auth help contains renoise auth exec, instead of using grep. If check-plugin.mjs exits 2, surface its upgrade commands to the user before continuing with generation features that need the new plugin. If --ensure fails, the binary is still missing, required commands are absent, or authentication is missing, immediately read ${CLAUDE_SKILL_DIR}/../renoise-setup/SKILL.md completely and follow it through readiness, asking only for approvals required before host PATH edits or browser authorization. Then rerun preflight and continue the original request; do not merely direct the user to Setup / Account. Never ask the user to paste an API key into chat.

Select a Model Dynamically

Treat renoise model --json as authoritative and current. Read ../model-routing/SKILL.md before choosing:

1. If the user names a model, preserve that choice.
2. Otherwise classify the task and filter candidates by required live capabilities.
3. Choose the best available specialist from model-routing; use the server-advertised isDefault only when no specialist clearly fits.
4. Apply the selected model's prompting profile, then inspect it before submitting:

renoise model <model> --json

Only pass ratios, resolutions, durations, material roles, reference counts, and audio options advertised there. Never copy those values into project documentation; new models and capability changes must work without a plugin release.

Analyze Media

Use the native analysis command for local images and videos:

# Standalone image/video understanding
renoise analyze <local-media-path> --target image|video --language <user-language> --json

# Replacement template for reference-video remake workflows
renoise analyze <local-media-path> --mode template --target video --language <user-language> --json

Use the structured analysis, prompt, slots, and warnings fields. Preserve source dialogue verbatim and label inferred motion or cross-media details as warnings. If analysis is unavailable, malformed, blocked, or truncated, treat it as failed; do not fabricate a result or fall back to copied model code.

Analysis never proves that generation will pass moderation, never creates a paid generation task, and must not silently upload the source to the material library.

Generate

For caller attribution, prefix every renoise task create invocation with RENOISE_CLIENT_NAME=codex in Codex or RENOISE_CLIENT_NAME=claude-code in Claude Code. Do not set it for other hosts or persist it globally. In PowerShell, set $env:RENOISE_CLIENT_NAME immediately before task creation and remove it afterward.

Agents must create the task first, record task.id from stdout, then wait separately. This makes terminal timeouts resumable and prevents a blind retry from creating and charging for another task:

renoise task create [model] \
  --prompt-file /path/to/prompt.txt \
  [--type video|image|audio] \
  [--duration N|-1] [--ratio X:Y] [--resolution VALUE] \
  [--materials "ID:role[:index],..."] \
  [--watermark] [--audio-generation=false] --json
renoise task wait <task-id> --timeout 15m --json

Use --prompt-file - to read a prompt from stdin, or --prompt only for short shell-safe text. The two flags are mutually exclusive. Omit the model to use the server default, or pass the selected model explicitly. Use --duration -1 only when the selected model's live guidance advertises automatic edit duration; otherwise pass a positive advertised duration.

If wait times out or the terminal call is interrupted, rerun wait with the same task ID; do not rerun create.

renoise task get <task-id> --json
renoise task result <task-id> --json
renoise task cancel <task-id> --json
renoise task list --json

Other operations:

renoise account status --json
renoise account history --json
renoise task cost <model> [generation options] --json
renoise task chain <task-id> --json
renoise task tags --json
renoise task tag <task-id> --tags project,shot --json
renoise material --json
renoise upload /path/to/file [--type image|video|audio] --json

Use renoise <command> --help rather than documenting every flag here.

Cost Gate

Before spending credits:

1. Run renoise task cost <model> ... --json with the actual generation parameters. For an automatic-duration edit, estimate with the source video's known positive duration, then create with --duration -1; stop if the source duration is unavailable.
2. Multiply estimatedCredit by the planned number of generations.
3. Add character-sheet, upscale, audio, and retry costs when applicable.
4. Compare with renoise account status --json.
5. Tell the user the estimate and wait for approval when the director workflow requires it.

Never quote static prices.

Materials

Upload once and reuse the returned material ID:

renoise upload /path/to/reference.png --json
renoise material --search reference --json

Material syntax is ID:role[:index]. The role is required; use only roles listed by renoise model <model> --json. index controls provider reference ordering.

In prompt text, reference an attached material as @material:<ID> using the same positive ID passed in --materials (for example, @material:3683). IDs are exact even when filenames collide. Separate tokens with whitespace or punctuation; text following a token should not begin with a digit.

Frame roles are positional: first_frame anchors the opening and last_frame anchors the ending. Use either only when advertised, and follow the selected model's guidance for allowed role combinations.

Do not assume role combinations are portable across models. Inspect the selected model's capabilities and guidance, then let CLI/server validation reject unsupported combinations. Never run a plugin-side facepass/original-Seedance preparation flow; default selection and reference handling belong to the live model response.

For a completed result that should become a reusable reference:

renoise task chain <task-id> --json

Prompt Basics

• Follow the selected model's live guidance and model-routing prompting profile.
• Describe subject, action, camera, scene, lighting/style, and sound as concrete sentences.
• Put technical controls such as ratio, resolution, duration, and material roles in CLI flags, not prose.
• Keep spoken lines verbatim in the user-confirmed language.
• For narrative, recurring-character, or multi-segment work, route through the director skill before generating.

Multi-Segment Mechanics

Tasks are stateless. Repeat the approved style/character text and reattach shared material IDs on every segment that needs them.

Choose continuity from the selected model's advertised material roles:

• Reuse a stable image material when identity, product, scene, or palette must stay fixed.
• Use task chain when a completed result can be reused through a supported video-reference role.
• If first_frame is supported, extract and upload the previous tail frame before the next segment.
• If only image references are supported, the director may use the tail frame as the first ordered image and describe the intended opening state explicitly.

Example tail-frame extraction:

ffmpeg -sseof -0.2 -i generated/shots/S1.mp4 -frames:v 1 -q:v 2 -y generated/keyframes/S1-end.jpg
renoise upload generated/keyframes/S1-end.jpg --json

Do not hard-code reference limits or model-specific role exclusions here.

Local Production Helpers

All executable helpers live under this local-only skill. Run only the helper needed for the current task:

# Batch upload/analyze materials, then match them to shots
node ${CLAUDE_SKILL_DIR}/scripts/material-ingest.mjs ./materials/
node ${CLAUDE_SKILL_DIR}/scripts/match-materials.mjs --pool material-pool.json --shots project.json

# Preview/QC and grid helpers used by director workflows
bash ${CLAUDE_SKILL_DIR}/scripts/qc-preview.sh --videos-dir <videos-dir>
bash ${CLAUDE_SKILL_DIR}/scripts/split-grid.sh storyboard.png output-dir/ 2 3

Other bundled helpers (batch-generate.sh, generate-preview.mjs, analyze-beats.py) are local implementation tools. Inspect their help/source before use; never run them in a Hosted Agent. Local end-to-end command examples live under examples/ in this Skill.

Errors

Use the CLI's JSON error and exit code; do not infer API behavior from copied endpoint documentation. JSON errors expose retryable and, after task creation, taskId; retry only the wait/query operation for that ID, never the paid create operation.

renoise task get <task-id> --json
renoise auth status --json
renoise model <model> --json

Do not pre-screen prompts or materials and do not infer a moderation result yourself. Continue the normal approval and submission flow unless the CLI/API returns an explicit content-review error (INPUT_* / OUTPUT_*). On that actual error, report it and stop; never retry the paid create operation or suggest bypasses.

References

• Prompt Craft — creative prompt and continuity methodology
• Native CLI help: renoise --help, renoise <command> --help
• Live capabilities: renoise model --json