CLI Reference

rnz

A CLI bridge that lets AI coding agents like Claude Code read, understand, and modify Renoise songs over UDP. Analyze patterns, write notes, load samples, add effects, automate parameters, and build full arrangements — programmatically.

# Clone and build
git clone https://github.com/juliarvalenti/rnz.git
cd rnz && pnpm install && pnpm run build

# Install the Renoise tool (symlink)
ln -s "$(pwd)/renoise/com.rnz.Bridge.xrnx" \
  ~/Library/Preferences/Renoise/V3.5.0/Scripts/Tools/com.rnz.Bridge.xrnx

# Reload tools in Renoise, then:
rnz ping

Commands

play

Start playback

rnz play

stop

Stop playback

rnz stop

bpm

Get or set BPM

rnz bpm [value]

Argument	Description
`value` optional	BPM to set (omit to read)

lpb

Get or set lines per beat

rnz lpb [value]

Argument	Description
`value` optional	LPB to set (omit to read)

new

Create a new empty song

rnz new

load

Load a song file

rnz load <path>

Argument	Description
`path` required	Path to .xrns file

automate

Create a linear automation sweep on a device parameter

rnz automate <pattern> <track> <device> <param> <from> <to>

Argument	Description
`pattern` required	Pattern index
`track` required	Track index
`device` required	Device index
`param` required	Parameter name
`from` required	Start value (0-1)
`to` required	End value (0-1)

sequence-add

Add a pattern to the sequence

rnz sequence-add

Option	Description
`--position <pos>`	Insert position (default: end)
`--pattern <pat>`	Existing pattern number to reference
`--lines <lines>`	Pattern length for new patterns

sequence-remove

Remove a position from the sequence

rnz sequence-remove <position>

Argument	Description
`position` required	Sequence position to remove

song

Show song info

rnz song

tracks

List all tracks

rnz tracks

instruments

List all instruments

rnz instruments

sequence

Show the pattern sequence order

rnz sequence

ping

Check if Renoise bridge is running

rnz ping

eval

Execute Lua code in Renoise and return the result

rnz eval <code>

Argument	Description
`code` required	Lua code to evaluate (must return a value)

pattern

Read/write pattern data

pattern length

Get or set pattern length in lines

rnz pattern length <pattern> [lines]

Argument	Description
`pattern` required	Pattern index (1-based)
`lines` optional	Number of lines to set (omit to read)

pattern read

Read pattern track data as JSON

rnz pattern read <pattern> <track>

Argument	Description
`pattern` required	Pattern index (1-based)
`track` required	Track index (1-based)

Option	Description
`--compact`	Only show non-empty lines
`--from <line>`	Start line (1-based)
`--to <line>`	End line (1-based)

pattern write

Write pattern track data from stdin JSON

rnz pattern write <pattern> <track>

Argument	Description
`pattern` required	Pattern index (1-based)
`track` required	Track index (1-based)

pattern clear

Clear a pattern track

rnz pattern clear <pattern> <track>

Argument	Description
`pattern` required	Pattern index (1-based)
`track` required	Track index (1-based)

pattern clone

Clone a pattern in the sequence

rnz pattern clone [position]

Argument	Description
`position` optional	Sequence position to clone (default: last)

pattern copy-track

Copy a track from one pattern to another

rnz pattern copy-track <src-pattern> <src-track> <dest-pattern> <dest-track>

Argument	Description
`src-pattern` required	Source pattern index
`src-track` required	Source track index
`dest-pattern` required	Destination pattern index
`dest-track` required	Destination track index

track

Track operations

track mute

Mute a track

rnz track mute <track>

Argument	Description
`track` required	Track index (1-based)

track unmute

Unmute a track

rnz track unmute <track>

Argument	Description
`track` required	Track index (1-based)

track solo

Solo a track

rnz track solo <track>

Argument	Description
`track` required	Track index (1-based)

track name

Get or set track name

rnz track name <track> [name]

Argument	Description
`track` required	Track index (1-based)
`name` optional	Name to set (omit to read)

track add

Add a new sequencer track

rnz track add <name>

Argument	Description
`name` required	Track name

track devices

List DSP devices on a track

rnz track devices <track>

Argument	Description
`track` required	Track index (1-based)

track fx-list

List available native effects

rnz track fx-list <track>

Argument	Description
`track` required	Track index (1-based)

track add-fx

Add a DSP effect to a track

rnz track add-fx <track> <device>

Argument	Description
`track` required	Track index (1-based)
`device` required	Device path (from fx-list)

Option	Description
`--position <pos>`	Insert position

track rm-fx

Remove a DSP effect from a track

rnz track rm-fx <track> <device>

Argument	Description
`track` required	Track index (1-based)
`device` required	Device index (1-based)

track fx-params

Show parameters of a DSP device

rnz track fx-params <track> <device>

Argument	Description
`track` required	Track index (1-based)
`device` required	Device index (1-based)

track set-fx

Set a DSP device parameter

rnz track set-fx <track> <device> <param> <value>

Argument	Description
`track` required	Track index (1-based)
`device` required	Device index (1-based)
`param` required	Parameter name
`value` required	Value to set

instrument

Instrument operations

instrument copy

Copy an instrument to another slot

rnz instrument copy <src> <dst>

Argument	Description
`src` required	Source instrument index
`dst` required	Destination instrument index

instrument clear

Clear an instrument

rnz instrument clear <instrument>

Argument	Description
`instrument` required	Instrument index

instrument add

Add a new instrument

rnz instrument add [name]

Argument	Description
`name` optional	Instrument name

Option	Description
`--position <pos>`	Insert position

instrument macro

Get or set instrument macros

rnz instrument macro <instrument> [macro] [value]

Argument	Description
`instrument` required	Instrument index
`macro` optional	Macro index 1-8 (omit to list all)
`value` optional	Value to set (0-1)

instrument set

Set an instrument property (volume, trigger_options.monophonic, phrase_playback_mode, etc.)

rnz instrument set <instrument> <prop> <value>

Argument	Description
`instrument` required	Instrument index
`prop` required	Property path (dot notation for nested)
`value` required	Value to set

instrument rm-mod

Remove a modulation device from an instrument

rnz instrument rm-mod <instrument> <device>

Argument	Description
`instrument` required	Instrument index
`device` required	Device index (1-based)

Option	Description
`--set <set>`	Modulation set index (default: 1) (default: 1)

instrument name

Get or set instrument name

rnz instrument name <instrument> [name]

Argument	Description
`instrument` required	Instrument index (1-based)
`name` optional	Name to set (omit to read)

instrument show

Show instrument details including ADSR and modulation

rnz instrument show <instrument>

Argument	Description
`instrument` required	Instrument index (1-based)

instrument modulations

List available modulation devices for an instrument

rnz instrument modulations <instrument>

Argument	Description
`instrument` required	Instrument index (1-based)

Option	Description
`--set <set>`	Modulation set index (default: 1) (default: 1)

instrument add-mod

Add a modulation device to an instrument

rnz instrument add-mod <instrument> <device>

Argument	Description
`instrument` required	Instrument index (1-based)
`device` required	Device name (from 'instrument modulations')

Option	Description
`--set <set>`	Modulation set index (default: 1) (default: 1)
`--target <target>`	Target: volume\|pan\|pitch\|cutoff\|resonance\|drive (default: volume) (default: volume)
`--position <pos>`	Insert position

instrument filter

Get or set the modulation filter type

rnz instrument filter <instrument> [type]

Argument	Description
`instrument` required	Instrument index (1-based)
`type` optional	Filter type to set (omit to list available)

Option	Description
`--set <set>`	Modulation set index (default: 1) (default: 1)

instrument mod-info

Show a modulation device's parameters and properties

rnz instrument mod-info <instrument> <device>

Argument	Description
`instrument` required	Instrument index (1-based)
`device` required	Device index (1-based)

Option	Description
`--set <set>`	Modulation set index (default: 1) (default: 1)

instrument set-param

Set a modulation device parameter

rnz instrument set-param <instrument> <device> <param> <value>

Argument	Description
`instrument` required	Instrument index (1-based)
`device` required	Device index (1-based)
`param` required	Parameter name
`value` required	Value to set

Option	Description
`--set <set>`	Modulation set index (default: 1) (default: 1)

instrument set-prop

Set a modulation device property (e.g. tempo_synced)

rnz instrument set-prop <instrument> <device> <prop> <value>

Argument	Description
`instrument` required	Instrument index (1-based)
`device` required	Device index (1-based)
`prop` required	Property name
`value` required	Value to set (true/false/number)

Option	Description
`--set <set>`	Modulation set index (default: 1) (default: 1)

sample

Sample operations

sample index

Recursively index a sample directory and write samples.md

rnz sample index <path>

Argument	Description
`path` required	Root directory to crawl

Option	Description
`-o, --output <file>`	Output file path (default: samples.md)

sample browse

Browse filesystem for samples

rnz sample browse <path>

Argument	Description
`path` required	Directory path to browse

sample load

Load a sample file into an instrument

rnz sample load <instrument> <path>

Argument	Description
`instrument` required	Instrument index (1-based)
`path` required	Path to sample file

Option	Description
`--slot <slot>`	Sample slot (default: append)
`--name <name>`	Name for the sample

sample map

Map a sample slot to a single note (for drumkits)

rnz sample map <instrument> <slot> <note>

Argument	Description
`instrument` required	Instrument index (1-based)
`slot` required	Sample slot (1-based)
`note` required	Note to map to (e.g. C-4, D-4, F#4)

sample info

Show sample properties and audio info

rnz sample info <instrument>

Argument	Description
`instrument` required	Instrument index

Option	Description
`--slot <slot>`	Sample slot (default: 1) (default: 1)

sample add

Add an empty sample slot to an instrument

rnz sample add <instrument> [name]

Argument	Description
`instrument` required	Instrument index
`name` optional	Sample name

sample set

Set a sample property (loop_mode, transpose, fine_tune, beat_sync_enabled, beat_sync_lines)

rnz sample set <instrument> <prop> <value>

Argument	Description
`instrument` required	Instrument index
`prop` required	Property name
`value` required	Value to set

Option	Description
`--slot <slot>`	Sample slot (default: 1) (default: 1)

sample save

Save a sample to a WAV file

rnz sample save <instrument> <path>

Argument	Description
`instrument` required	Instrument index
`path` required	Output file path

Option	Description
`--slot <slot>`	Sample slot (default: 1) (default: 1)

sample analyze

Analyze a sample — transient detection, energy profile (JSON output)

rnz sample analyze <instrument>

Argument	Description
`instrument` required	Instrument index (1-based)

Option	Description
`--slot <slot>`	Sample slot (default: 1) (default: 1)
`--window <ms>`	Analysis window in ms (default: 10)
`--threshold <t>`	Transient detection threshold (RMS jump ratio) (default: 2.0)

Notation Guide

The gen commands use a notation inspired by pattrns and Tidal Cycles.

Notes

Notes are written as name + octave: c4, eb5, f#3. Use off for note-off and ~ for rest.

rnz gen notes 1 1 "c4  e4  g4  c5" --unit 1/4

Chords

Append a chord type with '. These expand to multi-column note data automatically.

Syntax	Chord	Intervals
`c4'M`	C major	0, 4, 7
`c4'm`	C minor	0, 3, 7
`c4'7`	C dominant 7	0, 4, 7, 10
`c4'M7`	C major 7	0, 4, 7, 11
`c4'm7`	C minor 7	0, 3, 7, 10
`c4'dim`	C diminished	0, 3, 6
`c4'aug`	C augmented	0, 4, 8
`c4'sus2`	C sus2	0, 2, 7
`c4'sus4`	C sus4	0, 5, 7

# Write a chord progression across the whole pattern
rnz gen progression 1 1 "f3'm  db3'M  ab3'M  eb3'M"

Note Properties

Add properties after the note, separated by spaces. Use double-space or | to separate events.

Property	Example	Description
`v`	`c4 v0.8`	Volume (0–1 → 00–80 hex)
`d`	`c4 d0.5`	Delay (0–1 → 00–FF hex)
`#`	`c4 #02`	Instrument number

rnz gen notes 1 1 "c4 v0.8  e4 v0.5  g4 v0.9" --unit 1/8

Pulse Strings

Define rhythms with x (hit) and . (rest), or use euclidean shorthand.

# x = hit, . = rest
rnz gen drums 1 2 --kick "x..x..x." --snare "....x..." --hat "xxxxxxxx"

# Euclidean rhythms: e(hits, steps)
rnz gen drums 1 2 --kick "e(3,8)" --snare "e(2,8)" --hat "e(5,8)"

# Preview a euclidean pattern
rnz gen euclidean 5 16
# → x..x..x..x..x...

Scales

Preview scale notes for composing melodies.

rnz gen scale f minor
# → F-4 G-4 G#4 A#4 C-5 C#5 D#5

rnz gen scale c pentatonic
# → C-4 D-4 E-4 G-4 A-4

Available scales: major, minor, dorian, phrygian, lydian, mixolydian, aeolian, locrian, pentatonic, minor-pentatonic, blues, chromatic, whole-tone.

Timing

The --unit flag controls how many lines each step occupies, relative to LPB.

Unit	At 8 LPB	Description
`1/1`	32 lines	Whole note
`1/2`	16 lines	Half note
`1/4`	8 lines	Quarter note (1 beat)
`1/8`	4 lines	Eighth note
`1/16`	2 lines	Sixteenth note
`1/32`	1 line	32nd note

Architecture

rnz has two parts: a TypeScript CLI that AI agents or humans invoke, and a Renoise Lua tool that runs a UDP server inside the DAW. The CLI sends JSON commands, the Lua tool executes them against the Renoise API, and returns results. Handlers are hot-reloaded on every request.

┌──────────┐    JSON/UDP:9876    ┌──────────────────┐
│  rnz CLI  │ ──────────────── │ Renoise Lua Tool │
│ TypeScript │ ◀──────────────── │   UDP server     │
└──────────┘                    └──────────────────┘

Commands are colocated — each has a command.ts (CLI) and handler.lua (Renoise) in the same folder. Handlers are hot-reloaded on every request, so changes take effect immediately without restarting Renoise.