renoise-setup

name	renoise-setup
description	Set up, update, or diagnose Renoise on any agent host. Use when the user asks to install, upgrade, configure, connect, log in, check dependencies, enable the Renoise CLI, or fix missing RENOISE_API_KEY, ffmpeg, jq, yt-dlp, ImageMagick, or agent-browser.
metadata	{"author":"renoise","version":"1.0.2","category":"setup","tags":["setup","install","authentication","dependencies","renoise"]}

Renoise Setup — Cross-Harness

This is the host-neutral setup flow. Do not assume Claude Code, Codex, OpenClaw, or a specific config directory. Resolve <PLUGIN_ROOT> as two directories above this skill's directory.

Another Renoise workflow may invoke this setup automatically when its preflight fails. Diagnose and preview immediately, then return to the original request after readiness is restored; do not make the user manually select Setup / Account.

Never ask the user to paste an API key into chat. Never install software, move binaries, edit PATH, or change host configuration without explicit confirmation.

0. Plugin copy freshness

Before fixing the CLI, check whether this installed plugin is behind the latest public release:

node "<PLUGIN_ROOT>/skills/renoise-setup/scripts/check-plugin.mjs"

• exit 0 — current (or newer than latest); continue
• exit 2 — print the script's host-specific upgrade commands and stop until the user updates/reinstalls the plugin and restarts the host; do not claim new plugin behavior is already active
• exit 1 — network/API failure; warn once and continue with CLI setup

Plugin installs are owned by each host marketplace. This check only guides the user; it cannot replace the plugin in place.

1. Detect, Install, or Update the Core Runtime

Detect without changing the host:

Host	Detection
macOS / Linux shell	command -v node; command -v renoise; uname -s; uname -m
Windows PowerShell	Get-Command node, renoise -ErrorAction SilentlyContinue; [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture

Node.js is required by the plugin's remaining material utilities and cross-platform installer scripts; Bun is optional. The native CLI is required and is the single source of truth for authentication, media analysis, model capabilities, generation, uploads, and task management.

If renoise exists, verify the plugin contract rather than trusting a static version number:

renoise version
renoise help task create
renoise help task wait
renoise help analyze
renoise help auth exec
renoise help auth login

The outputs must contain the exact usage paths renoise task create, renoise task wait, renoise analyze, and renoise auth exec, the task flag --prompt-file, the analyze flag --mode, plus the auth login flag --web; older Cobra builds may show parent help and still exit successfully.

Generation preflight auto-keeps the managed CLI current. It reads https://download.renoise.ai/cli/latest.json and installs/replaces only the managed target when missing, incompatible, or older than the latest public release — no prompt:

node "<PLUGIN_ROOT>/skills/renoise-setup/scripts/install-cli.mjs" --ensure

Host	Managed target
macOS / Linux	~/.local/bin/renoise
Windows	%LOCALAPPDATA%\Renoise\bin\renoise.exe

After --ensure, prefer that managed binary for the session (export PATH="$HOME/.local/bin:$PATH" on Unix, or prepend %LOCALAPPDATA%\Renoise\bin on Windows). --ensure never edits shell profiles or the Windows user environment.

For a dry run (no downloads), or when the user explicitly asks to inspect/install outside generation:

node "<PLUGIN_ROOT>/skills/renoise-setup/scripts/install-cli.mjs" --check

The installer supports macOS, Windows, and Linux on x64 or ARM64. It selects .tar.gz on macOS/Linux or .zip on Windows and verifies the archive against the release's checksums.txt.

Show the installed and latest versions, detected release archive, whether the target will replace an existing file, and target path. For manual --install outside generation preflight, ask for explicit confirmation first, then run:

node "<PLUGIN_ROOT>/skills/renoise-setup/scripts/install-cli.mjs" --install

If the managed target directory is absent from PATH or another renoise binary wins PATH resolution, explain the platform-specific change and ask separately before editing shell profiles or the Windows user environment. Restart Codex/ChatGPT Desktop or Claude Desktop after a PATH change. Linux has no official Codex Desktop app, but the same CLI and skills work in Codex CLI and Claude Code.

For manual installation, read the public release manifest at https://download.renoise.ai/cli/latest.json, download the matching archive and checksums.txt from its version directory, verify SHA-256, then extract the binary. Downloading, moving, or replacing files still requires confirmation.

Before replacing an existing binary, the installer checks all five command contracts. After installation, rerun the checks above. If agent-safe task create --prompt-file, task wait, analyze --mode, auth exec, or browser login is unavailable, the release is incompatible; stop and ask the user to upgrade rather than recreating the command in the plugin.

2. Authenticate Once

First run renoise auth status --json. If it is not authenticated, the Agent—not the user—must run:

renoise auth login --web --json

Keep the command running while it opens the Renoise authorization page. The user only signs in and selects Allow and connect in the browser; never ask them to open a terminal, copy an API key, or paste a secret into chat. The CLI receives the credential through a one-time localhost callback, validates it, and saves it in the OS user config directory with restricted permissions. After the command returns, continue setup automatically.

Plugin generation, media understanding, uploads, and Credits call the CLI directly. RENOISE_API_KEY remains the credential override for CI and containers, but the native CLI binary is still required.

Verify through the native CLI:

renoise account status --json
renoise model --json

If browser authentication fails, rerun renoise auth login --web --json. Only direct the user to account settings when the browser reports an account or permission error; do not fall back to secret entry in chat.

3. Check Workflow Readiness

Detection only on macOS/Linux:

for tool in jq ffmpeg ffprobe yt-dlp magick agent-browser; do
  if command -v "$tool" >/dev/null 2>&1; then printf 'OK      %s\n' "$tool"; else printf 'MISSING %s\n' "$tool"; fi
done

Windows PowerShell equivalent:

'jq','ffmpeg','ffprobe','yt-dlp','magick','agent-browser' | ForEach-Object {
  if (Get-Command $_ -ErrorAction SilentlyContinue) { "OK      $_" } else { "MISSING $_" }
}

Tool	Enables
jq	Director batch generation
ffmpeg + ffprobe	Assembly, tail frames, QC, audio mix, video inspection
yt-dlp	Video downloads
ImageMagick magick	Storyboard-grid splitting; optional QC fallback
agent-browser	Optional Douyin/TikTok download fallback

Offer only relevant missing tools, and install only after confirmation:

• macOS/Homebrew: brew install jq ffmpeg yt-dlp imagemagick
• Debian/Ubuntu: sudo apt install jq ffmpeg imagemagick; current yt-dlp: pipx install yt-dlp
• Windows/winget: winget install jqlang.jq Gyan.FFmpeg yt-dlp.yt-dlp ImageMagick.ImageMagick
• Optional browser fallback: npm install -g agent-browser && agent-browser install

Missing optional tools do not block generation or Gemini.

4. Report

Return a short readiness summary:

Renoise CLI: ready / missing
Authentication: ready / action needed
Generation + Gemini: ready / action needed
Director/QC: ready / limited by ...
Downloads: ready / limited by ...
Optional browser fallback: ready / not installed

Apply host-specific extras only when that host exposes them. For example, the Claude Code /renoise:setup wrapper may additionally configure its statusLine; that is not part of this universal flow.