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. 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.

Options

Option	Description
-m, --midi-port <NAME>	MIDI output port (partial match supported).
--list-ports	List available MIDI ports and exit.
--no-midi	Disable MIDI output. This is the default when no port is specified.
--multicore[=<BOOL>]	Enable multicore audio rendering. --multicore / --multicore=true on, --multicore=false off; omit to use the config file (default off).
--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 -m "IAC Driver" song.non # render, sending MIDI to a port
resonon --list-ports             # see available MIDI ports
resonon                          # start the REPL

Note

--multicore requires the = form when combined with a file (--multicore=true song.non), so a bare --multicore doesn’t swallow the filename. The RESONON_PARALLEL 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 visuals

Open the browser render page for a running server.

Option	Default	Description
--port <PORT>	5555	Server port.
--host <HOST>	127.0.0.1	Server host.

The render page is served by the server, so the server must already be running.

resonon version

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

Subcommand	Description
list (default)	List installed versions.
current	Print the active version.
switch <VERSION>	Switch the active version (may require sudo).

resonon version list
sudo resonon version switch v0.2.0

resonon plugin

Manage audio plugins (CLAP + VST3).

Subcommand	Description
scan	Scan plugin directories and update the caches.
list	List discovered plugins from the caches.

resonon plugin scan
resonon plugin list

Project & Package Commands

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

Command	Purpose
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 pkg …	install / list / inspect / update.

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

Environment Variables

Variable	Description
RESONON_HOME	Override the ~/.resonon home directory (config, lib, kits, …).
RESONON_MIDI_PORT	Default MIDI output port name.
RESONON_SERVER_PASSWORD	Default server password (used by server when --password is omitted).

Advanced audio-engine tuning (rarely needed): RESONON_PARALLEL, RESONON_WORKERS, RESONON_SPIN_BUDGET, and RESONON_PLUGIN_MOD_STRIDE override their respective config/CLI settings.

MIDI Port Resolution Order

The output port is resolved first-match-wins:

1. CLI flag (-m, --midi-port)
2. Environment variable (RESONON_MIDI_PORT)
3. Config file ([midi] output_port)

Startup Sequence

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

1. Initializes logging and extracts embedded CLAP plugins.
2. Parses CLI arguments; subcommands (view, version, pkg, plugin, …) handle their work and exit early.
3. Handles --list-ports (prints ports and exits).
4. Loads ~/.resonon/config.toml.
5. Initializes the audio engine with the configured output device.
6. Connects MIDI ports (the default port plus any named [[midi.outputs]]).
7. Starts the REPL or runs the specified file.

See Also

• Configuration — config.toml, the ~/.resonon layout, and environment variables
• Server & Collaboration — running and connecting to the server
• Troubleshooting — MIDI, audio, and headless-mode issues