vtubestudio-cli (vts)

CLI program for sending one-off requests to the [VTube Studio API]. It connects to the websocket, authenticates, performs one or two other requests, and then disconnects and exits.

The primary use case is to do infrequent actions such as triggering hotkeys or registering custom parameters, without needing to establish a long-running websocket connection.

For more complex tasks, you might want to look at client libraries like [vtubestudio-rs] (the Rust library that this program uses under the hood).

Download

Check the releases page to download prebuilt binaries for your platform.

Otherwise you can use cargo install vtubestudio-cli or build it manually from this repo using cargo build --release.

Initialization

vts reads auth token info from a JSON config file whose default location depends on platform.

To generate the config in the default location, you can run:

sh vts config init

This will register the plugin with the VTube Studio API (the user will get a pop-up in the app asking for confirmation) and save the token for use in future calls. The plugin name and developer name can be customized with --plugin-name and --developer-name, respectively.

Config file location

By default, the config file can be found at:

• Windows: %USERPROFILE%\AppData\Roaming\walfie\vtubestudio-cli\config.json
• macOS: $HOME/Library/Application Support/com.github.walfie.vtubestudio-cli/config.json
• Linux: $XDG_CONFIG_DIR/vtubestudio-cli/config.json or $HOME/.config/vtubestudio-cli/config.json

This path can be overridden by setting the VTS_CONFIG environment variable or passing the --config-file flag.

You can also run vts config path to show the path to the config, or vts config show to show the contents of the config file.

Usage

Hotkeys

• List hotkeys

  sh vts hotkeys list

• Trigger hotkey by id

  sh vts hotkeys trigger e50ef5139b114d63af342eb65072a5e3

• Trigger hotkey by name

  sh vts hotkeys trigger --name MyHotkeyName

Artmeshes

• List artmeshes

  sh vts artmeshes list

• Tint artmesh (rainbow)

  sh vts artmeshes tint --rainbow --duration 5s --tag-contains shirt sleeves

  VTube Studio resets artmesh tints when the plugin disconnects. Since this CLI program normally disconnects immediately after executing commands (which would otherwise reset the tint), the --duration flag adds a delay afterwards, to keep the tint active.

• Tint artmesh (hex color)

  sh vts artmeshes tint --color ff0000 --duration 5s --tag-contains eye

  The hex color also supports alpha, so values like ff0000aa are also valid.

Params

• Create parameter

  sh vts params create MyParameterName --default 0 --min 0 --max 50

• Inject parameter value

  sh vts params inject MyParameterName 5

• Get value of parameter

  sh vts params get MyParameterName

Models

• List models

  sh vts models list

• Load model by ID

  sh vts models load 8caf15fa0c664f489873386e43835a7f

• Load model by name

  sh vts models load --name Akari

• Move model

  sh vts models move --relative --duration 0.5s --rotation 180

Expressions

• Get expression list.

  sh vts expression list --details

• Activate expression.

  sh vts expression activate myExpression_1.exp3.json

Physics

• Get physics settings.

  sh vts physics get

• Set base physics strength (default 500ms).

  sh vts physics set base strength 50

• Set base wind strength for 3 seconds.

  sh vts physics set base wind 50 --duration 3s

• Set strength multiplier.

  sh vts physics set multiplier strength 1 --id PhysicsSetting1

• Set wind multiplier.

  sh vts physics set multiplier wind 0.5 --id PhysicsSetting1

Others

sh vts --help