Command line
project init
Initialize a new .vibrai project file
Project name (default: basename of —project, i.e. the current directory name)
Path to .vibrai file (default: <current-directory-name>.vibrai in the working directory; auto-uniquified to <name>-2.vibrai, etc. if it already exists)
Write opinionated demo content (3 sections, 2 parts, exercises variation + scale overrides + naming) instead of the boilerplate
Seed from a genre library by id or display name (run ‘vibrai genre list’)
Preset id or display name within —genre (default: first preset alphabetically)
Persist Ableton ’#’ track auto-numbering into the new project.
Overwrite the file at —project if it already exists (without this, init refuses rather than destroying an existing project)
Project time signature, e.g. “7/8”. Omit to leave it undeclared, in which case Vibrai follows Live’s transport. Values are numerator/denominator; numerator 1-99, denominator one of 1, 2, 4, 8, 16.
project load
Load and display a project file
Path to the .vibrai file (default: <current-directory-name>.vibrai in the working directory)
project save
Save the current project state
Path to the .vibrai file (default: <current-directory-name>.vibrai in the working directory)
project info
Show project file info
Path to the .vibrai file (default: <current-directory-name>.vibrai in the working directory)
project config
Edit persisted project preferences (e.g. —number-tracks)
Path to the .vibrai file (default: <current-directory-name>.vibrai in the working directory)
Persist Ableton ’#’ track auto-numbering: true or false.
Project time signature, e.g. “7/8”.
project clear
Delete all Vibrai-generated tracks from the Live set (clean slate before a new generate)
Confirm deletion of Vibrai-generated tracks. Deletion targets MIDI tracks that are not group/folder tracks and whose part type (inferred from the track’s current name, not stored) is not ‘other’. Because part type is name-inferred, a user track like ‘My Bass’ may be selected. Without this flag, lists the tracks that would be deleted and exits non-zero.
MCP tools
init_project
Create a new .vibrai YAML file at the given absolute path. Without demo, writes a minimal 2-section / 1-part boilerplate. With demo: true, writes an opinionated 3-section / 2-part starter that exercises variation, per-section scale overrides, naming, and both generator types. Track IDs are probed from the bridge (first N MIDI tracks, skipping group/folder tracks) and each probed binding records the track’s current name (part track_name) so generate reuses those tracks; if the bridge is unreachable, falls back to track 1 (and 2 for demo) with no binding. Set number_tracks=true to persist Ableton ’#’ track auto-numbering into the new project’s Defaults. Refuses with PROJECT_EXISTS if a file already exists at path — pass force=true to overwrite it.
String
required
Absolute filesystem path for the new .vibrai file.
String
Project display name. Defaults to the basename of
path (e.g. “my-song” for …/my-song.vibrai).Boolean
If true, write the demo content instead of the boilerplate.
Boolean
Persist Ableton ’#’ track auto-numbering into the new project.
Boolean
Overwrite an existing file at
path. Without this, init refuses rather than destroying an existing project.String
Project time signature, e.g. “7/8”. Omit to leave it undeclared, in which case Vibrai follows Live’s transport. Values are numerator/denominator; numerator 1-99, denominator one of 1, 2, 4, 8, 16.
load_project
Load a .vibrai YAML file from the given absolute path. Returns the VibraiProject. Returns null if the file is missing.
String
required
Absolute filesystem path to the .vibrai file.
save_project
Save a VibraiProject (same shape as load_project’s return value) to the given absolute path, overwriting any existing file. Validates the project first; rejects invalid input (e.g. section modifier <= 0) without writing the file.
String
required
Absolute filesystem path to write to.
VibraiProject
required
Project document, same shape as load_project’s return value.
project_info
Return a summary of the project (counts of sections, parts, templates, and a scale block: root/name for what a fresh render targets, source_root/source_name for what the underlying genre data was authored in — null on hand-authored/pre-v5 projects) at the given path.
String
required
Absolute filesystem path to the .vibrai file.
configure_project
Edit project-level preferences in an existing .vibrai file. Currently: number_tracks (persist Ableton ’#’ track auto-numbering) and time_signature. Loads, updates project.defaults / project.meta, and saves. Pass at least one of number_tracks or time_signature. Errors if the file is missing.
String
required
Absolute filesystem path to the .vibrai file.
Nullable`1
Persist Ableton ’#’ track auto-numbering (true) or disable it (false). Omit to leave unchanged.
String
Project time signature, e.g. “7/8”. Omit to leave unchanged.
clear_project
Delete every Vibrai-generated track from the current Live set — a clean slate before rendering a different composition into the same set (the fix for successive generate runs of different projects stacking tracks after each other). Selection rule: MIDI tracks that are not group/folder tracks and whose part type — inferred from the track’s current name on every read, not a stamp stored on the track — is not ‘other’; a user’s own tracks, template tracks, group tracks, and Audio/Return/Master tracks are never touched. Because the part type is name-inferred, a user track whose name happens to match a part keyword (e.g. “My Bass”) can also be selected. Deletes highest-index-first, one at a time. Destructive — requires confirm=true (parity with the CLI’s project clear --yes); without it, errors listing exactly what would be deleted and changes nothing. When nothing is Vibrai-generated, succeeds trivially without requiring confirm.
Boolean
Confirm the destructive delete (CLI —yes equivalent). Must be true to proceed when there is anything to clear; confirm with the user first.