SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsrenoise-cli

renoise-cli

Design & creation

View repository

Updated 10-15 17:17

About this skill

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 create | grep -q -- '--source-width'
renoise help task cost | grep -q -- '--edit'
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, renoise task cost plus --edit, and renoise task wait; analyze help must contain --mode, and auth help must contain 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. CLI v0.7.5 sends local videos through 60 MiB inline so Colorist can offload media above its configured threshold to GCS; larger videos still use the older temporary upload path and may fail. CLI analysis does not independently probe exact video duration as Hosted Agent does: verify local duration before enforcing source limits or estimating automatic-duration edits. 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.

renoise task create is a paid-operation boundary. Do not invoke it until the current conversation contains an explicit post-preview approval for the exact final prompt and generation arguments described in the Cost Gate below. A general instruction to generate immediately, given before the preview, is intent to use the workflow—not approval of an unseen prompt or price.

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] \
  [--source-width PX --source-height PX [--source-duration SECONDS]] \
  [--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. For automatic-duration video editing, cost estimation and creation intentionally use different duration values: estimate with --edit --duration <positive-source-duration-seconds>, then create with --duration -1 --ratio adaptive.

--source-width and --source-height carry generic, measured source-media facts; --source-duration is optional. Use them only when output metadata cannot be specified up front (for example an adaptive ratio) and a trusted local source provides those values. They do not mark the task as an edit, do not replace --ratio/--duration, and explicit output parameters remain authoritative.

For a Seedance source-video edit created with --duration -1, the final prompt written to --prompt-file must explicitly tell the model to add, modify, remove, or edit the video. For deterministic routing, append [Edit the video as instructed above] as the final line unless that exact trigger is already present. Apply this only to source-video editing. Do not append the edit trigger or use --duration -1 for forward/backward extension or ordinary reference-based generation; those flows use their live positive duration and their own extension/generation wording.

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] [--scope user|mask] --json

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

Cost Gate

Before spending credits:

  1. Finish the exact final prompt first, including model-specific adapters, material tokens, preservation constraints, and required system/edit trigger text. The displayed prompt must be byte-for-byte the text later written to --prompt-file.
  2. Run renoise task cost <model> ... --json with the actual generation parameters. For an automatic-duration edit, run renoise task cost <model> --edit --duration <positive-source-duration-seconds> --resolution <resolution> ... --json, then create with --duration -1 --ratio adaptive; stop if the source duration is unavailable. --edit belongs to task cost, not task create.
  3. Multiply estimatedCredit by the planned number of generations and add character-sheet, upscale, audio, and retry costs when applicable.
  4. Compare with renoise account status --json.
  5. Present the complete final prompt in a fenced block plus the selected model, media type, resolution, duration/ratio, ordered material IDs and roles, generation count, estimated credits, and current balance.
  6. Wait for one explicit approval immediately before executing the disclosed paid batch. This gate applies to every paid generation path, including annotation-board submissions; it is never waived by an earlier “直接生成” instruction or by approval of a source directory, upload, storyboard, or annotation intent. Do not ask for an earlier duplicate approval.
  7. After approval, create with the exact approved prompt and arguments. If any prompt text, model, parameter, material mapping, generation count, or estimate changes, show the revised proposal and obtain approval again.

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

Uploads default to --scope user, which appears in the user's reusable material library. Use --scope mask only for tool-generated intermediate images such as annotated video frames or image-annotation composites. Mask-scoped materials remain addressable by their returned positive material ID for prompts and generation tasks but are excluded from normal material-library listings.

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