Client tool (vive-ctl)
Command-line interface for controlling ViveEngine via gRPC
vive-ctl [command] [global flags] [command flags]
Global Flags
-A, --address string engine rpc address (auto-discover if empty)
-T, --timeout duration rpc timeout (default 1m0s)
-j, --json output in json format
Commands
- vive-ctl engine
- vive-ctl license
- vive-ctl plugin
- vive-ctl mode
- vive-ctl flow
- vive-ctl effect
- vive-ctl caption
- vive-ctl device
- vive-ctl event
- vive-ctl manual
- vive-ctl completion
Commands
vive-ctl engine
List and check status of discovered ViveEngine instances.
Each running engine publishes a local metadata file on startup. These subcommands read those files to enumerate the instances and probe the default one, without requiring an explicit address.
vive-ctl engine list
List all discovered ViveEngine instances from local metadata files.
Each running engine publishes a metadata file locally; this command reads those files and reports the instances without connecting to any engine. Use --json for machine-readable output.
vive-ctl engine list [flags]
Aliases: ls, l
Command Flags
-H, --no-header hide table header
vive-ctl engine status
Show status of the default ViveEngine instance.
Reads the default engine's metadata and connects to its RPC address to report whether it is currently online.
vive-ctl engine status [flags]
Aliases: st, s
vive-ctl license
Query activation status, activate and deactivate license.
Licensing controls whether the engine may run audio processing, and the license type governs which features are available. A successful activation is persistent: it survives restarts until the license expires, is revoked, or is deactivated.
vive-ctl license status
Retrieve the current license state from ViveEngine.
Reports the activation type and, when a license is active, its full or trial activation details, without changing the license.
vive-ctl license status [flags]
Aliases: st
vive-ctl license activate
Activate ViveEngine license using either --trial, --key, or --email.
Contacts the licensing service and may take noticeably longer than other commands. A successful activation persists across restarts.
Exactly one activation method is required. With --email a password is also needed: it is taken from --password, or read from the terminal when --password is omitted or set to "-". Likewise --key reads the key from the terminal when given no value or "-".
Examples:
vive-ctl license activate --trial
vive-ctl license activate --key XXXX-XXXX-XXXX
vive-ctl license activate --key -
vive-ctl license activate --email user@example.com --password secret
vive-ctl license activate [flags]
Aliases: act, a
Command Flags
-t, --trial activate trial license
-k, --key string[="-"] activate with license key (read from stdin if "-" or no value)
-e, --email string activate with user email (also needs password)
-p, --password string password for email activation (read from stdin if "-" or omitted)
vive-ctl license deactivate
Deactivate the current ViveEngine license.
Releases the current activation so it can be used on another computer. The engine stops audio processing until a license is activated again.
vive-ctl license deactivate [flags]
Aliases: deact, d
vive-ctl plugin
List, load, and unload ViveEngine plugins.
Plugins are external binaries that add custom audio effects. One loaded plugin can back any number of effect instances placed in flows. Loading is persistent: plugins are loaded again automatically after an engine restart.
vive-ctl plugin list
List all loaded plugins from ViveEngine.
Lists loaded plugin binaries, not the individual effect instances created from them. Use --long for full details or --json for machine-readable output.
vive-ctl plugin list [flags]
Aliases: ls, l
Command Flags
-l, --long enable long output format
-H, --no-header hide table header
vive-ctl plugin load
Load a plugin into ViveEngine.
Loads the binary at --location as the given --type and reports the assigned plugin UID, which is then used to add plugin effects and to address the plugin in messaging. Loading is persistent and idempotent: loading an already loaded plugin returns its existing UID, which is stable across unload and reload.
Both --type and --location are required. --type is either "native", a shared library loaded into the engine process, or "golang", a managed plugin run as a separate process.
Example:
vive-ctl plugin load --type native --location /path/to/plugin.so
vive-ctl plugin load [flags]
Aliases: ld
Command Flags
-t, --type string plugin type: native or golang
-L, --location string plugin location/path
vive-ctl plugin unload
Unload a plugin from ViveEngine.
Removes the plugin identified by --uid from the persistent set, so it is not loaded again after a restart. All effect instances created from it are destroyed and removed from the flows that contained them.
--uid is required.
vive-ctl plugin unload [flags]
Aliases: ul
Command Flags
-u, --uid string UID of the plugin to unload
vive-ctl mode
Query and control input/output processing run mode.
Run mode is the master switch that controls whether the engine is active on audio input, output, or both. When a direction is disabled, audio passes through the OS as if ViveEngine were not installed, while all configuration is preserved and restored when it is enabled again.
vive-ctl mode get
Retrieve the current run mode from ViveEngine.
Reports whether input and output processing are currently enabled.
vive-ctl mode get [flags]
Aliases: g
vive-ctl mode set
Enable or disable input and/or output processing.
Only the directions passed are changed; the other keeps its current value. Each value is "on" or "off".
At least one of --input or --output is required.
Examples:
vive-ctl mode set --input on
vive-ctl mode set --input on --output off
vive-ctl mode set [flags]
Aliases: s
Command Flags
-i, --input string set input processing: on or off
-o, --output string set output processing: on or off
vive-ctl flow
Query and configure audio flow (route and effect chain).
A flow is the configuration of one logical input or output of an application or device. It consists of a route, selecting which device is used, and an effect chain that processes the audio. A flow is selected by its direction (--dir) and scope (--scope).
vive-ctl flow query
Query current audio flow configuration (route and effect chain).
Locates the flow by --dir and --scope and prints its current route and effect chain. Use --long for a detailed listing or --json for machine-readable output.
--dir is required.
vive-ctl flow query [flags]
Aliases: q
Command Flags
-D, --dir string flow direction: input or output
-s, --scope string flow scope: default (default "default")
-l, --long use long output format
vive-ctl flow configure
Configure audio flow route and/or effect chain.
Replaces the configuration of the flow selected by --dir and --scope, setting its route and effect chain in a single call. Omitting --route resets the route to the default device, and omitting the effect chain clears all effects; use the effect subcommands to change individual effects one at a time instead.
--dir is required.
The effect chain is given as positional arguments after the flags, as a sequence of effects. Each effect is an effect name followed by its flags:
{effect} [flag]... [{effect} [flag]...]...
Effects are applied in the order listed, and each accepts -k/--key to set its key (auto-assigned when omitted). Because flags are not interspersed with the chain, all command flags must appear before the first effect name.
Example:
vive-ctl flow configure --dir output gain -c 6 eq -b 100,8000 -g 3,-2
The effects available for the chain, along with the options each accepts, are listed below. The same options for a single effect are shown by "{effect} -h".
Available Effects:
gain - channel gain adjustment
-k, --key UINT effect key
-c, --chans FLOAT,... channel gains
equalizer (eq) - equalizer with frequency bands
-k, --key UINT effect key
-b, --bands FLOAT,... band frequencies
-g, --gains FLOAT,... band gains
noise_reduction (nr) - noise reduction filter
-k, --key UINT effect key
-m, --mode dsp|rnn algorithm name
range_compression (drc) - dynamic range compression
-k, --key UINT effect key
-b, --boost FLOAT boost level
-r, --ratio FLOAT compression ratio
-l, --levels FLOAT,FLOAT,FLOAT bass,mids,treble target levels
captioning (cap) - real-time speech-to-text
-k, --key UINT effect key
-l, --lang STRING language code
plugin (plug) - third-party plugin effect
-k, --key UINT effect key
-u, --uid STRING plugin UID
-p, --protoset PATH protoset file for custom config message
-t, --msg-type NAME fully-qualified custom config message name
-j, --msg-json JSON custom config message as JSON
vive-ctl flow configure [flags]
Aliases: conf, c
Command Flags
-D, --dir string flow direction: input or output
-s, --scope string flow scope: default (default "default")
-l, --long use long output format
-r, --route string device UID for route
vive-ctl effect
Query and configure individual effects in a flow's effect chain.
Unlike flow configure, which replaces the whole chain at once, these subcommands change one effect at a time. An effect is addressed by the flow it belongs to (--dir and --scope) and its effect key.
An effect argument is written as an effect name followed by its flags, for example "gain -c 6". Run "vive-ctl flow configure --help" for the list of available effects, or pass -h after an effect name to list that effect's flags.
vive-ctl effect add
Insert a new effect into the flow's effect chain.
The effect is given as positional arguments: an effect name followed by its flags (for example "gain -c 6"). Run "vive-ctl flow configure --help" for the list of available effects, or pass -h after an effect name to list that effect's flags.
By default the effect is appended; use --pos to insert at a zero-based position. A key is auto-assigned unless the effect carries -k/--key. --dir is required, and all command flags must appear before the effect name.
Example:
vive-ctl effect add --dir output --pos 0 eq -b 100,8000 -g 3,-2
vive-ctl effect add [flags]
Aliases: a
Command Flags
-D, --dir string flow direction: input or output
-s, --scope string flow scope: default (default "default")
-p, --pos int position in effect chain (default: append) (default -1)
vive-ctl effect get
Query a single effect from the flow's effect chain by key.
Locates the effect by --dir/--scope and --key and prints its configuration. Fails if no effect with that key exists.
Both --dir and --key are required.
vive-ctl effect get [flags]
Aliases: g
Command Flags
-D, --dir string flow direction: input or output
-s, --scope string flow scope: default (default "default")
-k, --key string effect key
vive-ctl effect set
Reconfigure an existing effect in the flow's effect chain.
The replacement effect is given as positional arguments, the same way as for effect add, and must carry -k/--key to identify the effect to replace; its position is kept. Run "vive-ctl flow configure --help" for the list of available effects, or pass -h after an effect name to list that effect's flags.
--dir is required, and the effect must include -k/--key. All command flags must appear before the effect name.
Example:
vive-ctl effect set --dir output gain -k 5 -c 3
vive-ctl effect set [flags]
Aliases: s
Command Flags
-D, --dir string flow direction: input or output
-s, --scope string flow scope: default (default "default")
vive-ctl effect delete
Remove an effect from the flow's effect chain by key.
Locates the effect by --dir/--scope and --key and removes it, shifting later effects toward the start. Fails if no effect with that key exists.
Both --dir and --key are required.
vive-ctl effect delete [flags]
Aliases: del, rm
Command Flags
-D, --dir string flow direction: input or output
-s, --scope string flow scope: default (default "default")
-k, --key string effect key
vive-ctl effect move
Reorder an effect within the flow's effect chain.
Moves the effect identified by --key to the zero-based --pos. The move is not atomic: it queries, deletes, then reinserts the effect, with no rollback if a step fails.
--dir, --key, and --pos are all required.
Example:
vive-ctl effect move --dir output --key 5 --pos 0
vive-ctl effect move [flags]
Aliases: mv
Command Flags
-D, --dir string flow direction: input or output
-s, --scope string flow scope: default (default "default")
-k, --key string effect key
-p, --pos int target position in effect chain (default -1)
vive-ctl caption
Real-time speech-to-text.
Captioning transcribes speech in an audio stream into live text captions. It is enabled by adding a captioning effect to a flow's effect chain; these subcommands select the provider and stream the resulting captions.
vive-ctl caption receive
Receive captions from ViveEngine until interrupted (Ctrl+C).
Streams captions from every flow that has captioning enabled, printing each as it arrives until interrupted. Captions include partial results, refined while a phrase is spoken, followed by a final result.
Use --device to show only captions from one device UID, --long for detailed output, or --json for machine-readable output.
vive-ctl caption receive [flags]
Aliases: recv, r
Command Flags
-d, --device string filter captions by device UID
-l, --long enable long output format
vive-ctl caption configure
Configure captioning provider and credentials.
Selects the captioning provider. The "billed" provider uses the built-in service and needs no credentials. The "byoc" provider (Bring Your Own Cloud) uses your own cloud account and requires credentials.
--provider is required. --aws-access-key and --aws-secret-key are required for "byoc" and must not be used with "billed".
Example:
vive-ctl caption configure --provider billed
vive-ctl caption configure --provider byoc \
--aws-access-key KEY --aws-secret-key SECRET
vive-ctl caption configure [flags]
Aliases: conf, c
Command Flags
-p, --provider string captioning provider: billed or byoc
--aws-access-key string AWS access key (BYOC only)
--aws-secret-key string AWS secret key (BYOC only)
vive-ctl device
Manage audio devices in ViveEngine.
Devices are the audio endpoints provided by the operating system, such as microphones and speakers. Each has a stable UID that is used to select it as a flow's route.
vive-ctl device list
List all available audio devices from ViveEngine.
Reports input and output devices, each with its UID, name, driver, and features. Exactly one input and one output device are marked as the current system default.
--match keeps only devices having at least one of the given features, while --exclude drops devices having any of them; both are repeatable. Features include input, output, default, virtual, builtin, headset, and bluetooth. Use --long for detailed output or --json for machine-readable output.
Example:
vive-ctl device list --match headset
vive-ctl device list --exclude virtual
vive-ctl device list [flags]
Aliases: ls, l
Command Flags
-l, --long enable long output format
-H, --no-header hide table header
-m, --match strings show only devices that has at least one of given features (repeatable)
-x, --exclude strings show only devices that don't have any of given features (repeatable)
vive-ctl event
Stream events from ViveEngine.
Events report changes in the engine's state, caused either by user actions such as changing the configuration, or by the operating system, such as a device being connected or disconnected.
vive-ctl event receive
Receive events from ViveEngine until interrupted (Ctrl+C).
Streams engine events, printing each as it arrives until interrupted. Each event carries a code identifying what changed; read the new state through the relevant command.
Use --long for detailed output or --json for machine-readable output.
vive-ctl event receive [flags]
Aliases: recv, r
Command Flags
-l, --long enable long output format
vive-ctl manual
Generate manual for vive-ctl commands in markdown or troff (man page) format.
Writes a single document covering all commands to standard output. Use --format markdown (the default) for documentation, or --format troff for a man page. Use --title to override the document title.
Example:
vive-ctl manual --format troff > vive-ctl.1
vive-ctl manual [flags]
Aliases: man
Command Flags
-f, --format string output format: markdown or troff (default "markdown")
-t, --title string document title
vive-ctl completion
Generate the autocompletion script for vive-ctl for the specified shell. See each sub-command's help for details on how to use the generated script.
vive-ctl completion bash
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source <(vive-ctl completion bash)
To load completions for every new session, execute once:
Linux:
vive-ctl completion bash > /etc/bash_completion.d/vive-ctl
macOS:
vive-ctl completion bash > $(brew --prefix)/etc/bash_completion.d/vive-ctl
You will need to start a new shell for this setup to take effect.
vive-ctl completion bash
Command Flags
--no-descriptions disable completion descriptions
vive-ctl completion zsh
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrc
To load completions in your current shell session:
source <(vive-ctl completion zsh)
To load completions for every new session, execute once:
Linux:
vive-ctl completion zsh > "${fpath[1]}/_vive-ctl"
macOS:
vive-ctl completion zsh > $(brew --prefix)/share/zsh/site-functions/_vive-ctl
You will need to start a new shell for this setup to take effect.
vive-ctl completion zsh [flags]
Command Flags
--no-descriptions disable completion descriptions
vive-ctl completion fish
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
vive-ctl completion fish | source
To load completions for every new session, execute once:
vive-ctl completion fish > ~/.config/fish/completions/vive-ctl.fish
You will need to start a new shell for this setup to take effect.
vive-ctl completion fish [flags]
Command Flags
--no-descriptions disable completion descriptions
vive-ctl completion powershell
Generate the autocompletion script for powershell.
To load completions in your current shell session:
vive-ctl completion powershell | Out-String | Invoke-Expression
To load completions for every new session, add the output of the above command to your powershell profile.
vive-ctl completion powershell [flags]
Command Flags
--no-descriptions disable completion descriptions