CLI Reference

The resonon binary runs a file, drops into a REPL, or manages the runtime around it (server, views, versions, plugins). This page covers the runtime CLI. For the project and package commands (init, new, install, …), see the Package Management guide.

Running Code

resonon [OPTIONS] [FILE]

Argument	Description
[FILE]	resonon file to run offline. Must sit inside a project. Omit for the interactive REPL.

Running a file renders it once and exits — this is the offline-rendering path. The REPL and the VSCode extension are the live-coding paths.

A piece belongs to a project. The project is found by walking up from the file for a resonon.toml, so a file plays the same whichever directory you invoke resonon from — and a file with no manifest above it is refused before anything is opened:

No resonon.toml in /Users/you/scratch or above it.
A piece belongs to a project — start one with `resonon new <name>`, or `resonon init` in the folder it should live in.

The REPL walks up from the working directory instead, so start it inside the project you mean to work in. See Package Management for resonon new and resonon init.

Options

Option	Description
--list-ports	List attached MIDI devices with paste-ready declarations, and exit.
--no-midi	Disable MIDI. Port declarations still succeed and still get an alias, so a file evaluates identically with and without hardware — nothing is opened and nothing is sent. For CI and headless rendering.
--multicore[=<BOOL>]	Enable multicore audio rendering. --multicore / --multicore=true on, --multicore=false off; omit to use the config file (default off).
--plugin-auto-scan[=<BOOL>]	Sweep the plugin folders in the background at startup. --plugin-auto-scan=false off; omit to use the config file (default on).
--plugin-mod-stride <N>	Samples between external-plugin automation points (default 16). 1 = per-sample.
-h, --help	Print help.
-V, --version	Print version.

resonon song.non                 # render a file once
resonon --list-ports             # see attached MIDI devices
resonon --no-midi song.non       # render with MIDI disabled (CI, headless)
resonon                          # start the REPL

Note

--multicore and --plugin-auto-scan take their value with = only, so a bare --multicore song.non doesn’t swallow the filename. The flip side: a space-separated value is read as the file, not as the value — --plugin-auto-scan false turns auto-scan on and tries to run a file called false. Write --plugin-auto-scan=false to turn it off. The RESONON_PARALLEL, RESONON_PLUGIN_AUTO_SCAN, and RESONON_PLUGIN_MOD_STRIDE environment variables override these flags when set.

resonon server

Start the WebSocket server for remote code execution and TUI views.

Option	Default	Description
--server-port <PORT>	5555	WebSocket server port.
--server-host <HOST>	0.0.0.0	Server host address.
--server-name <NAME>	hostname	Custom name for discovery.
--password <PASS>	—	Require a password (falls back to RESONON_SERVER_PASSWORD).

resonon server --server-port 6000 --server-name "studio"

resonon view <NAME>

Launch a TUI view connected to a running server. Views: console, midi_monitor, mixer, routing, scope.

Option	Description
--port <PORT>	Server port (omit for the auto-discovery connection screen).
--host <HOST>	Server host (omit for auto-discovery).
--midi-port <NAME>	MIDI input filter for the midi_monitor view (partial match).
--password <PASS>	Password for a protected server.

resonon view mixer --host 10.0.0.5 --port 5555

resonon version

Manage installed resonon versions (stored under ~/.resonon/versions/).

Subcommand	Description
list (default)	List installed versions.
current	Print the active version.
install <VERSION>	Download and install a published version. Does not activate it.
switch <VERSION>	Make an installed version active.

Option	Applies to	Description
--switch	install	Make it active once installed.
--force	install	Re-download over an existing install.
--install	switch	Download it first if it is not on this machine.

<VERSION> is spelled as resonon version list prints it — bare, with no v prefix (0.11.0, not v0.11.0), though a v is accepted and ignored.

Installing and switching are separate on purpose. Switching repoints ~/.resonon/versions/current, which changes what every shell and any running language server resolve — so install never does it unless you ask.

resonon version list
resonon version install 0.12.0            # fetch it, stay where you are
resonon version switch 0.12.0             # activate a version you already have
resonon version switch 0.12.0 --install   # both, in one go

switch --install is the one to reach for when a project asks for a version you do not have — it is what the mismatch message and the VSCode “Switch Version” button run.

No sudo: everything under ~/.resonon belongs to you, and sudo would relink root’s ~/.resonon instead of yours.

resonon plugin

Manage audio plugins (CLAP + VST3).

Subcommand	Description
scan	Update the plugin database. Only new or changed bundles are opened.
scan --force	Re-open every bundle, including ones skipped after crashing or hanging.
rescan <path>…	Re-open just the named bundles, whatever the database says about them.
list	List discovered plugins, and report any bundles that were skipped.

resonon plugin scan
resonon plugin scan --force
resonon plugin rescan ~/Library/Audio/Plug-Ins/VST3/Whatever.vst3
resonon plugin list

rescan is --force narrowed to one bundle: the way back for a plugin that was skipped, without paying for a full re-scan of everything else you own. It exits non-zero if a named bundle still will not load. In the editor the same retry is plugin_rescan(path), usually reached as the plugin-named Retry … quick fix on the error itself.

Any run that starts the audio engine — a file, the REPL, resonon run, a server — sweeps in the background and keeps the database up to date on its own, so these are mostly for scripting and for diagnosing a plugin that will not appear. See Finding Plugins.

resonon setup

This machine’s Preferences, asked one page at a time: the audio interface in and out, the sample rate and block size, the recording offset, the MIDI ports and what your pieces call them, the kit and plugin folders, and the width viz() draws a cycle at.

resonon setup

Each page offers what this rig actually has — devices and ports off a list rather than typed from memory — and opens on whatever ~/.resonon/preferences.toml already says, so pressing ⏎ through it changes nothing. Nothing is written until the last page, which names every line that would change; esc writes nothing at all. A file you have commented keeps its comments.

resonon new offers to run it on a machine with no preferences file yet, and only where there is a terminal to answer in. Without one, resonon setup names the written way to do each of the same things instead of waiting for a key nobody can press. See Configuration.

resonon config

Command	Purpose
resonon config paths	Every directory resonon searches, in order, and where each came from.
resonon config kits add / remove / list	This machine’s [folders] kits, without opening the file.
resonon config plugins add / remove / list	The same for [folders] plugins.

Project & Package Commands

These scaffold projects and manage dependencies. They’re covered in the Package Management guide:

Command	Purpose
resonon run	Run the project’s entry point (src/main.non) from anywhere inside the project.
resonon init <name>	Scaffold a project in the current directory.
resonon new <name>	Create a project in a new directory.
resonon build	Build a native extension.
resonon install [src]	Install a package, or all from resonon.toml.
resonon update [name]	Update dependencies.
resonon remove <name>	Remove a dependency.
resonon collect [kit]	Copy a kit into the project so it travels with it, recording where it came from. Omit the name to work through everything resonon.toml declares.
resonon kits list	The kits this project depends on from outside it, and where each one is.
resonon kits remove <n>	Forget a declaration. The kit’s own files are left alone.
resonon pkg …	install / list / inspect / update.
resonon setup	Set up this machine — audio, MIDI, folders. See above.

init, new, and build accept --lib, --kit, and --native flags to choose the project type.

collect and kits are the tools for a project that depends on your own kit library — see Sharing a Project.

Environment Variables

Variable	Description
RESONON_HOME	Override the ~/.resonon home directory (preferences, kits, versions, caches). Must be an absolute path to a directory, or to nothing yet — resonon makes it. Anything else, including a path with a file already at it, is ignored with a warning and ~/.resonon stands.
RESONON_SERVER_PASSWORD	Server password. Beats --password, and the startup line says which of the two it took.
RESONON_PLUGIN_AUTO_SCAN	Turn the startup plugin sweep on or off. Beats --plugin-auto-scan.
RESONON_LOG	Log level: off, error, warn, info, debug, trace. Falls back to RUST_LOG, then info.

Advanced audio-engine tuning (rarely needed): RESONON_PARALLEL, RESONON_WORKERS, RESONON_SPIN_BUDGET, and RESONON_PLUGIN_MOD_STRIDE override their respective CLI settings. RESONON_SUBPROCESS_SCAN=0 makes plugin scanning open bundles in resonon’s own process instead of an isolated child — a debugging aid that gives up crash isolation, so a plugin that dies on load takes the session with it.

All of these speak one dialect — environment beats flag beats default, on/off is 1/true/yes/on against 0/false/no/off, empty means “not given”, and a value resonon cannot read stops it starting rather than picking a side. RESONON_HOME is the exception, and Configuration says why.

MIDI Ports

MIDI ports are preferences, not command-line arguments: [[midi.outputs]] and [[midi.inputs]] in ~/.resonon/preferences.toml, opened before the first bar of every session. resonon --list-ports prints a paste-ready entry per attached device:

[[midi.outputs]]
alias = "daw"
port  = "IAC Driver Bus 1"

reload_preferences() puts a change in force without restarting. See Configuration.

Startup Sequence

When you run resonon with a file or the REPL, it:

1. Initializes logging and extracts embedded CLAP plugins.
2. Reads ~/.resonon/preferences.toml. Before the command branches, so that resonon config paths and the plugin scan see the same folders a session does.
3. Parses CLI arguments; subcommands (view, version, pkg, plugin, …) handle their work and exit early.
4. Handles --list-ports (prints attached devices as preferences entries, and exits). resonon setup branches here too, for the same reason: it edits the file that was just read, and opens no audio device of its own.
5. For a file: resolves the project it belongs to, and the resonon version that project targets. Before the audio device, so a file that belongs to no project — or one written for a newer resonon — says so without first claiming an interface and putting a window on screen. The REPL has no file to anchor on, so it reaches the same answer at the first thing you evaluate.
6. Resolves [audio] against this machine’s hardware, naming anything it cannot honour, and opens the output device at that rate and block size.
7. Starts the plugin sweep on a background thread, unless auto-scan is off. This happens for a file, the REPL, and the server alike, and nothing waits on it.
8. Opens the declared MIDI ports, then runs the file or starts the REPL. Everything in preferences is in force before the first line of your code.

See Also

• Configuration — where each kind of setting lives, the ~/.resonon layout, and environment variables
• Server & Collaboration — running and connecting to the server
• Troubleshooting — MIDI, audio, and headless-mode issues