Instruments - Vibrai

Browse, tag, and manage instruments in the Vibrai library.

Command line

`instrument list`

List browser items (with optional tag/search/kind filters)

vibrai instrument list --search <TEXT> --path-contains <TEXT> --path-prefix <PREFIX> --kind <PRESET|DEVICE|RACK> --tagged --untagged --tag <SUFFIX> --include-extra --offset <N> --limit <N>

--search

Filter by name substring (case-insensitive)

--path-contains

Filter by browser path substring (case-insensitive)

--path-prefix

Only items whose browser path starts with this prefix

--kind

Filter by item kind

--tagged

Only items with at least one user tag

--untagged

Only items without any user tag

--tag

Only items tagged with vibrai:<suffix> (e.g. —tag bass). Case-insensitive.

--include-extra

When used with —tag, also match unrecognized extra-tag suffixes

--offset

default:"0"

Skip this many qualifying results (for pagination, default 0)

--limit

default:"50"

Max results (default 50)

`instrument tag`

Apply a Vibrai PartType tag to an instrument

vibrai instrument tag <uri-or-search> <part-type>

uri-or-search

required

Browser URI (exact, contains ’:’ + ’#’) or name substring (case-insensitive, single match required)

part-type

required

PartType to apply (case-insensitive). Use an invalid value to see the full list.

`instrument untag`

Remove a Vibrai PartType tag from an instrument

vibrai instrument untag <uri-or-search> <part-type>

uri-or-search

required

Browser URI (exact) or name substring (single match required)

part-type

required

PartType to remove (case-insensitive)

`instrument show`

Show one instrument record with all tags

vibrai instrument show <uri-or-search>

uri-or-search

required

Browser URI (exact) or name substring (single match required)

`instrument suggest`

Suggest PartType tags from folder names (read-only, does not mutate)

vibrai instrument suggest --prefix <PATH> --pattern-set <NAME>

--prefix

Scope suggestions to this browser path prefix (e.g. ‘Packs/F9 GALAXY’). Omit to scan all items.

--pattern-set

Pattern set to use. Only ‘default’ is supported.

MCP tools

`find_instruments_by_tag`

Find user presets tagged ‘vibrai:<suffix>’. Returns all matches: their browser URI (pass as load_device ‘path’), display name, browser path, and the recognized/extra tag buckets. Empty array if no matches or no cache file. Tags are populated by the Vibrai Live remote script — see install_vibrai_remote_script.

{
  "tool": "find_instruments_by_tag",
  "arguments": {
    "suffix": "<String>",
    "include_extra": "<Boolean>"
  }
}

suffix

String

required

Tag suffix to match (e.g. ‘bass’ for vibrai:bass). Case-insensitive.

include_extra

Boolean

required

If true, also matches unrecognized ‘extra’ tag suffixes. Default false.

`refresh_instrument_tags`

Ask the Vibrai Live remote script to rescan the browser. Touches the trigger file and waits up to 5 seconds for the browser snapshot to be rewritten. Returns the new scanned_at + item_count, or INSTRUMENT_TAG_SCRIPT_NOT_RUNNING if the script doesn’t respond. If you get the not-running error, run install_vibrai_remote_script and make sure Vibrai is enabled in Live’s Preferences → Link/Tempo/MIDI → Control Surface.

{
  "tool": "refresh_instrument_tags",
  "arguments": {}
}

`list_browser_items`

List items from the Vibrai browser snapshot, optionally filtered by name substring, path substring, path prefix, kind, or tagged state. The snapshot is written by the Vibrai Live remote script; the user tags items via tag_instrument. Returns up to limit results starting at offset (for pagination).

{
  "tool": "list_browser_items",
  "arguments": {
    "search": "<String>",
    "path_contains": "<String>",
    "path_prefix": "<String>",
    "kind": "<String>",
    "tagged": "<Nullable`1>",
    "offset": "<Int32>",
    "limit": "<Int32>"
  }
}

String

required

Case-insensitive substring match against item name. Null/empty = all.

path_contains

String

required

Case-insensitive substring match against the full browser path (e.g. ‘Basses’ matches any item under a folder containing that word). Null = all.

path_prefix

String

required

Only return items whose browser path starts with this prefix (case-insensitive), e.g. ‘Packs/F9 GALAXY’. Null = all.

kind

String

required

Filter by kind: ‘preset’, ‘device’, ‘rack’. Null = all kinds.

tagged

Nullable`1

required

If true, only items with at least one user tag; if false, only untagged; null = both.

offset

Int32

required

Number of qualifying results to skip before returning (for pagination). Default 0.

limit

Int32

required

Max results to return (default 50).

`show_instrument`

Show one browser item plus any user tags applied to it. Accepts an exact uri (contains ’:’ and ’#’) or a name substring; case-insensitive. Errors: INSTRUMENT_NOT_FOUND, MULTIPLE_MATCHES.

{
  "tool": "show_instrument",
  "arguments": {
    "uri_or_search": "<String>"
  }
}

uri_or_search

String

required

Browser URI (exact match) or name substring (case-insensitive, single match required).

`tag_instrument`

Apply a Vibrai PartType tag to a browser item. Accepts an exact uri or a name substring (single match). Atomically updates instrument-tags.json. Errors: INSTRUMENT_NOT_FOUND, MULTIPLE_MATCHES, INVALID_PART_TYPE.

{
  "tool": "tag_instrument",
  "arguments": {
    "uri_or_search": "<String>",
    "part_type": "<String>"
  }
}

uri_or_search

String

required

Browser URI (exact) or name substring (case-insensitive, single match).

part_type

String

required

PartType to apply (case-insensitive). E.g. ‘bass’, ‘pad’, ‘lead’.

`untag_instrument`

Remove a Vibrai PartType tag from a browser item. If the item ends with no tags at all (recognized + extra both empty), the record is dropped from the tag store. Errors: INSTRUMENT_NOT_FOUND, MULTIPLE_MATCHES, INVALID_PART_TYPE.

{
  "tool": "untag_instrument",
  "arguments": {
    "uri_or_search": "<String>",
    "part_type": "<String>"
  }
}

uri_or_search

String

required

Browser URI (exact) or name substring (case-insensitive, single match).

part_type

String

required

PartType to remove (case-insensitive).

`suggest_tags_from_folders`

Scan the browser snapshot and infer PartType tags from folder names. Returns suggestions only — call tag_instrument to apply them. Use ‘prefix’ to scope to a single pack (e.g. ‘Packs/F9 GALAXY’). The default pattern set maps common folder names (Basses→Bass, Kicks→Bd, Pads→Pad, etc.) to PartTypes. Does not mutate any state.

{
  "tool": "suggest_tags_from_folders",
  "arguments": {
    "prefix": "<String>",
    "pattern_set": "<String>"
  }
}

prefix

String

required

Browser path prefix to restrict the scan (e.g. ‘Packs/F9 GALAXY’). Null/empty = entire snapshot.

pattern_set

String

required

Pattern set name. Only ‘default’ is supported. Null = default.

Documentation Index

​Command line

​instrument list

​instrument tag

​instrument untag

​instrument show

​instrument suggest

​MCP tools

​find_instruments_by_tag

​refresh_instrument_tags

​list_browser_items

​show_instrument

​tag_instrument

​untag_instrument

​suggest_tags_from_folders

Command line

`instrument list`

`instrument tag`

`instrument untag`

`instrument show`

`instrument suggest`

MCP tools

`find_instruments_by_tag`

`refresh_instrument_tags`

`list_browser_items`

`show_instrument`

`tag_instrument`

`untag_instrument`

`suggest_tags_from_folders`