Command Line

The resonon binary runs a project, drops into a REPL, or manages the runtime around it (server, views, versions, plugins). This page covers the runtime CLI. The project and package commands (init, new, install, …) are under Project & Package Commands.

Running Code

resonon run [OPTIONS]
resonon [OPTIONS]

With no command, start the interactive REPL. run evaluates the project’s entry point.

A piece is run by resonon run, in its project. A file named on the command line is not a way to run one: resonon song.non is a usage error. The project is the nearest directory at or above the working directory that holds a resonon.toml — the same one the resonon launcher read to choose the version that runs. resonon run evaluates src/main.non top to bottom and exits after its last statement. It writes files only where it asks to: audio where it calls render(), MIDI where it calls midi_export(). What it opens, and its exit status, are in File Runs.

The options go before or after run: resonon run --no-midi and resonon --no-midi run are the same.

With no resonon.toml at or above the working directory, resonon run and the REPL are 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.

resonon new and resonon init are under Project & Package Commands.

Options

resonon [OPTIONS] [COMMAND]

Argument	Default	Description
`--list-ports`	false	List available MIDI ports (with paste-ready declarations) and exit
`--no-midi`	false	Disable MIDI entirely. Port declarations still succeed and still get a stable alias, so a piece evaluates identically with and without hardware — nothing is opened and nothing is sent. For CI and headless rendering
`--multicore[=<MULTICORE>]`	—	Enable multicore audio rendering. `--multicore` or `--multicore=true` turns it on; `--multicore=false` off; omit for the default (off). `RESONON_PARALLEL` overrides this flag. An explicit value requires `=`
`--plugin-mod-stride <PLUGIN_MOD_STRIDE>`	—	Samples between external-plugin parameter automation points. Default: 16 (about 0.33 ms at 48 kHz); `1` is per-sample. Must be at least 1. `RESONON_PLUGIN_MOD_STRIDE` overrides this flag. Custom DSP remains per-sample
`--plugin-auto-scan[=<PLUGIN_AUTO_SCAN>]`	—	Sweep the plugin folders in the background at startup. Default: on. `--plugin-auto-scan=false` disables the sweep; a bare flag enables it. `RESONON_PLUGIN_AUTO_SCAN` overrides this flag. An explicit value requires `=`
`-h, --help`	—	Print help
`-V, --version`	—	Print version

resonon run                      # run the project's src/main.non
resonon --list-ports             # see attached MIDI devices
resonon run --no-midi            # run with MIDI disabled (CI, headless)
resonon                          # start the REPL

`resonon server`

resonon server [OPTIONS]

Start the WebSocket server for remote code execution

Argument	Default	Description
`--server-port <SERVER_PORT>`	5555	WebSocket server port
`--server-host <SERVER_HOST>`	0.0.0.0	WebSocket server host address
`--server-name <SERVER_NAME>`	—	Custom server name for discovery (defaults to hostname)
`--password <PASSWORD>`	—	Password required for client connections. `RESONON_SERVER_PASSWORD` overrides this flag. Startup reports which source it used

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

`resonon view <NAME>`

resonon view [OPTIONS] <NAME>

Launch a TUI view connected to a running server

Argument	Default	Description
`<NAME>`	—	View name (console, midi_monitor, mixer, routing, scope)
`--port <PORT>`	—	Server port (omit for connection screen with auto-discovery)
`--host <HOST>`	—	Server host (omit for connection screen with auto-discovery)
`--midi-port <MIDI_PORT>`	—	MIDI input port filter for the midi_monitor view (partial match)
`--password <PASSWORD>`	—	Password for connecting to a password-protected server

resonon view mixer --host 10.0.0.5 --port 5555

`resonon version`

resonon is a launcher. Run inside a project, it runs the Resonon version that project’s resonon.toml pins (package.resonon); outside a project, it runs the default. Versions live under ~/.resonon/versions/.

resonon version is the launcher’s own command, and answers the same whatever the project pins. With no subcommand, it lists installed versions.

resonon version [COMMAND]

Manage installed versions of Resonon

`resonon version list`

resonon version list

List installed versions, marking the default

`resonon version install`

resonon version install [OPTIONS] <VERSION>

Download and install a published version

Argument	Default	Description
`<VERSION>`	—	Version to install (e.g. 0.11.0), as it appears on the release page
`--switch`	false	Also make it the default, the version used where no project pins one
`--force`	false	Re-download over an existing install

`resonon version switch`

resonon version switch <VERSION>

Make an installed version the default, used where no project pins one

Argument	Default	Description
`<VERSION>`	—	Version to make the default, named as `resonon version list` shows it

`resonon version current`

resonon version current

Print the version that runs in this directory, and why

<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 a version is enough for the projects that pin it: from then on they run it. switch only changes the default. A running live server keeps the version it started with until it is restarted.

resonon version list
resonon version current                   # e.g. "0.12.1 (pinned by /songs/techno/resonon.toml)"
resonon version install 0.12.0            # projects pinning 0.12 now run it
resonon version switch 0.12.0             # make it the default outside projects

current always prints the version first, then why it runs here: (default), (pinned by …/resonon.toml), or (default; …/resonon.toml pins 0.13.0, not installed).

Run it without sudo: with sudo, it works on root’s ~/.resonon, not yours.

`resonon plugin`

resonon plugin [OPTIONS] <COMMAND>

Manage audio plugins (CLAP + VST3)

`resonon plugin scan`

resonon plugin scan [OPTIONS]

Scan plugin directories and update the plugin database (CLAP + VST3).

Only bundles that are new or have changed since the last scan are opened.

Argument	Default	Description
`--force`	false	Re-open every bundle, including ones blocklisted after crashing or hanging a previous scan

`resonon plugin rescan`

resonon plugin rescan [OPTIONS] <PATHS>...

Re-open specific plugin bundles, whatever the database already says.

--force scoped to one bundle: the way back for a plugin that was skipped, without paying for a full rescan of everything else.

Argument	Default	Description
`<PATHS>...`	—	Bundles to re-open (`.clap` or `.vst3`)

`resonon plugin list`

resonon plugin list [OPTIONS]

List discovered plugins from caches (CLAP + VST3)

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

rescan re-opens only the bundles it names, skipped ones included. 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 — resonon run, the REPL, a server — also sweeps in the background, unless auto-scan is off. See Find What Is Installed.

`resonon setup`

resonon setup [OPTIONS]

Set up this machine: audio, MIDI, folders — one question at a time

The Preferences dialog, in the terminal. Every setting ~/.resonon/preferences.toml holds, offered against the devices and ports this rig actually has, so an interface is chosen from a list rather than typed from memory. Nothing is written until the last page, which names every line that would change, and a file you have commented keeps its comments.

Needs a terminal. Without one it says what to run instead.

resonon setup

Edits ~/.resonon/preferences.toml one page at a time: audio input and output, sample rate, block size, recording offset, MIDI ports and their aliases, kit and plugin folders, and the viz() width.

Behaviour
Choices	Devices and ports this machine has, offered as a list.
Starting values	What the file already says; `⏎` keeps them.
Writing	Only on the last page, which lists every changed line. `esc` writes nothing.
Formatting	Comments, spacing and key order are kept.
Without a terminal	Prints the written way to make each setting, and exits.

See Set Up This Machine.

`resonon config`

resonon config [OPTIONS] <COMMAND>

Inspect the active configuration

`resonon config paths`

resonon config paths [OPTIONS]

Print every directory resonon searches, in order, and why.

“Where is it looking?” should not require reading the source. Each entry says where it came from — the project, this machine’s preferences, or the install — and whether it exists on disk.

`resonon config kits`

resonon config kits [OPTIONS] <COMMAND>

The folders this machine keeps sampler kits in.

[folders] kits in ~/.resonon/preferences.toml, which you may also edit by hand. Distinct from resonon kits, whose subject is what one project declares: this is the machine, that is the piece.

`resonon config kits add`

resonon config kits add [OPTIONS] <DIR>

Add a folder to the list.

A leading ~ is kept as written and expanded per machine. Relative paths are stored absolute. A quoted path naming $VAR is refused; an unquoted variable is expanded by the shell before Resonon sees it. A folder that is not there right now is still added and reported as absent — an unmounted drive is not a mistake.

Argument	Default	Description
`<DIR>`	—	Folder to search

`resonon config kits remove`

resonon config kits remove [OPTIONS] <DIR>

Take a folder off the list.

Either as it is written in the file or as it resolves on this machine.

Argument	Default	Description
`<DIR>`	—	Folder to stop searching

`resonon config kits list`

resonon config kits list [OPTIONS]

Print the list, as written and as it resolves

`resonon config plugins`

resonon config plugins [OPTIONS] <COMMAND>

The folders this machine keeps CLAP and VST3 plugins in.

[folders] plugins in ~/.resonon/preferences.toml. Added to the standard folders for this OS and to CLAP_PATH / VST3_PATH, never instead of them.

`resonon config plugins add`

resonon config plugins add [OPTIONS] <DIR>

Add a folder to the list.

Argument	Default	Description
`<DIR>`	—	Folder to search

`resonon config plugins remove`

resonon config plugins remove [OPTIONS] <DIR>

Take a folder off the list.

Either as it is written in the file or as it resolves on this machine.

Argument	Default	Description
`<DIR>`	—	Folder to stop searching

`resonon config plugins list`

resonon config plugins list [OPTIONS]

Print the list, as written and as it resolves

Project & Package Commands

These scaffold projects and manage dependencies. The tasks are in Install a Package, Publish a Package and Share a Project.

`resonon init`

resonon init [OPTIONS] <NAME>

Initialize a new project in the current directory

Argument	Default	Description
`<NAME>`	—	Project name
`--lib`	false	Create a library project (src/lib.non instead of src/main.non)
`--kit`	false	Create a sample kit project (kits/ directory)
`--native`	false	Create a native Rust extension project (implies —lib)

`resonon new`

resonon new [OPTIONS] <NAME>

Create a new project in a new directory

Argument	Default	Description
`<NAME>`	—	Project name (used as directory name)
`--lib`	false	Create a library project (src/lib.non instead of src/main.non)
`--kit`	false	Create a sample kit project (kits/ directory)
`--native`	false	Create a native Rust extension project (implies —lib)

`resonon build`

resonon build [OPTIONS]

Build native extension

Argument	Default	Description
`--dist`	false	Output with platform-specific name for binary distribution

`resonon install`

resonon install [OPTIONS] [SOURCE]

Install a package or all dependencies from resonon.toml

Argument	Default	Description
`[SOURCE]`	—	Package source (e.g. gh:user/repo or gh:user/repo@v1.0). Omit to install from resonon.toml

`resonon update`

resonon update [OPTIONS] [NAME]

Update installed packages to latest matching versions

Argument	Default	Description
`[NAME]`	—	Package name to update (omit to update all)

`resonon remove`

resonon remove [OPTIONS] <NAME>

Remove a dependency from the project

Argument	Default	Description
`<NAME>`	—	Package name to remove

`resonon collect`

resonon collect [OPTIONS] [KIT]

Copy a kit into the project so it travels with it

A kit resolved out of your own library plays here and is missing on the machine you send this project to. This brings it in — the name in your code does not change, because <project>/kits is searched first.

With no argument, collects every kit resonon.toml declares.

Argument	Default	Description
`[KIT]`	—	Kit to collect (omit to collect everything declared in resonon.toml)

`resonon kits`

resonon kits [OPTIONS] <COMMAND>

The kits this project depends on from outside it

A project’s own kits, in <project>/kits, need no declaration — they travel because they are already there. This list is the other ones: kits drawn from your library or from elsewhere on this machine, recorded so the project says where its sounds came from. resonon collect adds to it and satisfies it; nothing removes from it but you.

`resonon kits list`

resonon kits list [OPTIONS]

List what this project declares, and where each kit is right now.

Three answers, because the way out of each is different: a kit in the project travels already, a kit on this machine is one resonon collect away, and a kit that is nowhere has to come from whoever sent you the project.

`resonon kits remove`

resonon kits remove [OPTIONS] <NAME>

Forget a declaration — the project no longer draws on that kit

Only ever a decision, never a deduction: Kit(…) names can be computed, so nothing can work out on your behalf that a kit has stopped being used. The kit’s own files are left where they are.

Argument	Default	Description
`<NAME>`	—	Kit name, as it appears in resonon.toml

`resonon run`

resonon run [OPTIONS]

Run the project’s src/main.non

`resonon client`

resonon client [OPTIONS]

Bridge a running server to stdin/stdout, for editor integrations

Each line read from stdin is one JSON message sent to the server; each message the server sends is written to stdout as one line of JSON. The messages are the server’s own protocol, unchanged. Ends when stdin closes or the server closes the connection.

Argument	Default	Description
`--port <PORT>`	5555	Server port
`--host <HOST>`	127.0.0.1	Server host

`resonon pkg`

resonon pkg [OPTIONS] <COMMAND>

Manage RESONON packages

`resonon pkg install`

resonon pkg install [OPTIONS] [SOURCE]

Install a package (from source or all from resonon.toml)

Argument	Default	Description
`[SOURCE]`	—	Package source (e.g. gh:user/repo or gh:user/repo@v1.0). Omit to install from resonon.toml

`resonon pkg list`

resonon pkg list [OPTIONS]

List installed packages

`resonon pkg inspect`

resonon pkg inspect [OPTIONS] <NAME>

Inspect a package’s exports

Argument	Default	Description
`<NAME>`	—	Package name (directory name in lib path)

`resonon pkg update`

resonon pkg update [OPTIONS] [NAME]

Update installed packages to latest matching versions

Argument	Default	Description
`[NAME]`	—	Package name to update (omit to update all)

init and new take flags that choose the project type; they combine. A native extension implies a library.

Every scaffold writes resonon.toml, README.md, an MIT LICENSE and a .gitignore that excludes dependencies/ and renders/, and initializes a git repository unless it is already inside one. On a machine with no preferences file, and only in a terminal, it then offers to run resonon setup.

resonon pkg list shows a package’s type as [code] (it has src/lib.non), [kits] (it has kits/) or [code+kits].

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

Environment Variables

Each is read once at startup. Where a flag or VSCode setting does the same, it is listed beside it.

Variable	Accepts	Description
`RESONON_PARALLEL`	1, true, yes, on / 0, false, no, off (case-insensitive)	Multicore audio rendering. Default: off. Flag: `--multicore[=<BOOL>]`. VSCode: `resonon.audio.multicore`.
`RESONON_PLUGIN_AUTO_SCAN`	1, true, yes, on / 0, false, no, off (case-insensitive)	The plugin sweep at startup. Off makes scanning strictly manual. Default: on. Flag: `--plugin-auto-scan=<BOOL>`. VSCode: `resonon.plugins.autoScan`.
`RESONON_SUBPROCESS_SCAN`	1, true, yes, on / 0, false, no, off (case-insensitive)	Plugin scanning in an isolated child process. Off opens bundles in resonon’s own process: a debugging aid that gives up crash isolation, so a plugin that dies on load takes the session with it. Default: on.
`RESONON_PLUGIN_MOD_STRIDE`	a whole number, 1 or more	Samples between external-plugin automation points. `1` is per-sample. Default: 16. Flag: `--plugin-mod-stride <N>`. VSCode: `resonon.audio.pluginModStride`.
`RESONON_WORKERS`	a whole number, 1 or more	Audio worker threads.
`RESONON_SPIN_BUDGET`	a whole number, 0 or more	How long an idle audio worker spins before it parks.
`RESONON_LOG`	a level for resonon (warn, info, debug, trace), and/or target=level for another crate, comma-separated, e.g. debug,naga=info	The log filter. Falls back to `RUST_LOG`, then `info`. Warnings from resonon and errors from any crate are always shown.
`RESONON_SERVER_PASSWORD`	anything	The server password. Flag: `--password` (on `resonon server`).
`RESONON_RELEASE_BASE_URL`	anything	Release download base URL. Defaults to the published release service; used by the launcher when installing a version.
`RESONON_HOME`	an absolute path to a directory, or to nothing yet	The resonon home, `~/.resonon` by default. See Home & Search Paths.
`RESONON_STDLIB_PATH`	an absolute path to a directory that is there	A standard library of your own, in place of the one that ships with this build.

Every variable follows the same rules:

The environment variable wins, then the flag, then the default.
On/off is 1, true, yes or on against 0, false, no or off, in any case.
Unset and empty mean the same thing: not given. RESONON_WORKERS= falls through to the default.

A value resonon cannot read stops it starting, naming the variable and what it takes:

Error: RESONON_PARALLEL=ture is not a boolean.
  Accepted: 1, true, yes, on / 0, false, no, off (case-insensitive).

Except a location. An unusable RESONON_HOME or RESONON_STDLIB_PATH is ignored, the default stands, and the startup says so:

	Nothing there yet	Something else there, or a relative path
`RESONON_HOME`	Applied: resonon makes it.	Ignored; `~/.resonon` stands.
`RESONON_STDLIB_PATH`	Ignored; the shipped standard library stands.	Ignored; the shipped standard library stands.

Both are settled once, when the process starts. resonon config paths prints the directory that was actually taken.

Startup Sequence

When you run resonon run or the REPL, it:

Validates environment variables and initializes logging.
Reads ~/.resonon/preferences.toml and installs folder, display and MIDI declarations.
Parses CLI arguments and checks the project’s version pin. Management commands handle their work and exit early.
Extracts embedded plugins and bundled kits when needed; handles --list-ports and checks that a project is present.
Resolves operational flags and [audio] against this machine’s hardware.
Starts the plugin sweep in the background, unless auto-scan is off.
Opens audio and the declared MIDI ports before evaluating the first line of user code.
Runs src/main.non or starts the REPL.

Command Line

Running Code

Options

resonon server

resonon view <NAME>

resonon version

resonon version list

resonon version install

resonon version switch

resonon version current

resonon plugin

resonon plugin scan

resonon plugin rescan

resonon plugin list

resonon setup

resonon config

resonon config paths

resonon config kits

resonon config kits add

resonon config kits remove

resonon config kits list

resonon config plugins

resonon config plugins add

resonon config plugins remove

resonon config plugins list