Documentation

CLI reference

Reference for the Vectron command-line interface.

This page documents the user-facing vectron CLI. Configuration fields are documented separately in the vectron.toml reference and vectron.stack.toml reference.

Global options

Global options can be placed before the subcommand.

Option	Value	Default	Env	Notes
`--log-level`	tracing level	Unset	`VECTRON_LOG`	Examples: `trace`, `debug`, `info`.
`--trace-subscriber`	`pretty`, `json`	`pretty`	None	Controls tracing output format.
`--man`	flag	`false`	None	Prints the roff man page to stdout.

Core commands

Command	Purpose
`vectron start`	Launch the configured workspace in the foreground.
`vectron check`	Validate `vectron.toml`.
`vectron migrate`	Generate `vectron.toml` from supported legacy inputs such as `Procfile`.
`vectron init`	Write a new `vectron.toml` in the current directory.
`vectron status`	Query the local control endpoint for the current status.
`vectron restart <target>`	Restart one process or one instance through the control endpoint.
`vectron logs`	Tail logs through the control endpoint.
`vectron doctor`	Diagnose terminal support and configuration.
`vectron stack ...`	Scaffold and provision a local stack from `vectron.stack.toml` on macOS.
`vectron completions ...`	Generate or install shell completion scripts.

`vectron start`

vectron start loads ./vectron.toml, prepares the process plan, starts the supervisor, and runs the TUI when stdout is attached to a terminal.

For the keyboard model, focus areas, and interactive controls, see the Terminal UI guide.

Option	Value	Default	Env	Notes
`--quiet`	flag	`false`	None	Limits output to essentials.
`--dry-run`	flag	`false`	None	Prints the startup plan without running hooks, creating logs, writing runtime state, or launching processes.
`--alt-screen`	boolean	`true`	None	Disable with `--alt-screen=false` to keep output after exit.
`--only-groups`	group list	`[]`	None	Comma-separated or repeated. Starts processes that belong to at least one listed group.
`--skip-groups`	group list	`[]`	None	Comma-separated or repeated. Skips processes that belong to at least one listed group.
`--enable-groups`	group list	`[]`	None	Comma-separated or repeated. Re-enables groups listed in `global.disabled_groups`.
`--only-labels`	label list	`[]`	None	Comma-separated or repeated. Starts processes that have at least one listed label.
`--skip-labels`	label list	`[]`	None	Comma-separated or repeated. Skips processes that have at least one listed label.
`--enable-labels`	label list	`[]`	None	Comma-separated or repeated. Re-enables labels listed in `global.disabled_labels`.
`--tui-metrics`	`on`, `off`	`on`	`VECTRON_TUI_METRICS`	Enables process CPU/RSS metrics in the TUI.
`--tui-metrics-mode`	`auto`, `foreground`, `background`, `frozen`	`auto`	`VECTRON_TUI_METRICS_MODE`	Controls how metrics behave with terminal focus.
`--tui-metrics-interval`	duration	`1s`	`VECTRON_TUI_METRICS_INTERVAL`	Foreground partial refresh interval. Examples: `500ms`, `1s`.
`--tui-metrics-full-scan-interval`	duration	`10s`	`VECTRON_TUI_METRICS_FULL_SCAN_INTERVAL`	Foreground full scan interval.
`--tui-metrics-background-interval`	duration	`20s`	`VECTRON_TUI_METRICS_BACKGROUND_INTERVAL`	Background partial refresh interval when focus events are supported.
`--tui-metrics-background-full-scan-interval`	duration	`120s`	`VECTRON_TUI_METRICS_BACKGROUND_FULL_SCAN_INTERVAL`	Background full scan interval when focus events are supported.

Group and label list options accept either comma-separated values or repeated flags:

vectron start --only-groups api,worker
vectron start --only-groups api --only-groups worker
vectron start --only-labels public,optional

vectron start --dry-run prints the resolved startup table, including process GROUP and LABELS metadata when configured, without running hooks, creating logs, writing runtime state, or launching processes.

`vectron check`

vectron check validates ./vectron.toml without starting processes.

Option	Value	Default	Env	Notes
`--enable-groups`	group list	`[]`	None	Comma-separated or repeated. Validates with selected disabled groups re-enabled.
`--enable-labels`	label list	`[]`	None	Comma-separated or repeated. Validates with selected disabled labels re-enabled.

`vectron migrate`

vectron migrate generates ./vectron.toml from supported legacy config files such as Procfile. It refuses to overwrite an existing vectron.toml.

Option	Value	Default	Env	Notes
None	-	-	-	This command has no command-specific options.

`vectron init`

vectron init writes a minimal vectron.toml to the current directory. It refuses to overwrite an existing file. Use --example to write the complete built-in example to vectron.toml instead.

Option	Value	Default	Env	Notes
`--example`	flag	`false`	None	Write the complete built-in example instead of the minimal config.

`vectron status`

vectron status queries the running workspace through the control socket.

Option	Value	Default	Env	Notes
None	-	-	-	This command has no command-specific options.

`vectron restart`

vectron restart <target> restarts a process or a single instance through the control socket.

Argument	Value	Required	Notes
`<target>`	process or instance name	Yes	Examples: `web`, `web#1`.

`vectron logs`

vectron logs tails logs through the control socket.

Option	Value	Default	Env	Notes
`--target`	process or instance	Unset	None	Examples: `web`, `web#2`. Conflicts with `--process` and `--instance`.
`-p`, `--process`	process name	Unset	None	Filters a process. Conflicts with `--target` and `--instance`.
`--instance`	instance name	Unset	None	Example: `web#2`. Conflicts with `--target` and `--process`.
`--once`	flag	`false`	None	Streams once and does not follow. Conflicts with `--follow`.
`--follow`	boolean	`true`	None	Disable with `--follow=false`. Conflicts with `--once`.
`--json`	flag	`false`	None	Emits NDJSON log records.

`vectron doctor`

vectron doctor reports terminal and TUI capability information.

Option	Value	Default	Env	Notes
`--json`	flag	`false`	None	Emits the report as JSON.

`vectron doctor tui`

vectron doctor tui runs an interactive terminal capability probe.

Option	Value	Default	Env	Notes
`--timeout`	duration	`10s`	None	Probe duration. Examples: `500ms`, `10s`.
`--json`	flag	`false`	None	Emits the probe result as JSON.

`vectron stack`

Stack mode is currently macOS-only. Plugin IDs accepted by stack commands are listed in the built-in plugins page.

`vectron stack init`

vectron stack init writes a minimal vectron.stack.toml. It refuses to overwrite an existing file. Use --example to write the complete built-in stack example instead.

Option	Value	Default	Env	Notes
`--example`	flag	`false`	None	Write the complete built-in `vectron.stack.toml` example and stop.

`vectron stack provision`

vectron stack provision initializes .vectron_stack/, installs dependencies, and generates vectron.toml from an existing vectron.stack.toml.

Option	Value	Default	Env	Notes
`--force`	flag	`false`	None	Allows deleting a non-empty `.vectron_stack/data` directory.
`--dry-run`	flag	`false`	None	Prints the plan without making changes.
`--only`	plugin list	`[]`	None	Comma-separated or repeated. Uses only these plugins before implicit dependencies are added.
`--skip`	plugin list	`[]`	None	Comma-separated or repeated. Removes these plugins from the selected set.

`vectron stack check`

vectron stack check validates vectron.stack.toml and the derived/generated configuration without side effects.

Option	Value	Default	Env	Notes
`--only`	plugin list	`[]`	None	Comma-separated or repeated. Restricts the check to selected plugins.
`--skip`	plugin list	`[]`	None	Comma-separated or repeated. Removes selected plugins from the check.

`vectron stack landing-ids`

vectron stack landing-ids prints available nginx landing-page link IDs for nginx.landing.quick_links.

Option	Value	Default	Env	Notes
`--only`	plugin list	`[]`	None	Comma-separated or repeated. Restricts output to selected plugins.
`--skip`	plugin list	`[]`	None	Comma-separated or repeated. Removes selected plugins from output.

`vectron completions`

`vectron completions generate`

vectron completions generate prints a completion script to stdout.

Option	Value	Default	Env	Notes
`--shell`	`bash`, `fish`, `zsh`	Required	None	Selects the shell to generate completions for.

Generated completions include static CLI structure and dynamic value candidates:

vectron restart <target> completes process and instance names.
vectron logs --target, --process, and --instance complete runtime/config targets.
vectron start and vectron check group/label flags complete values from vectron.toml.
vectron stack provision/check/landing-ids --only and --skip complete built-in plugin IDs.

Dynamic process and instance candidates prefer the running control socket when Vectron is active, then fall back to the local config. Group and label candidates come from the local config. Plugin candidates come from the built-in stack plugin catalog. Comma-separated list flags complete the current item after the last comma.

`vectron completions install`

vectron completions install installs a completion script to a conventional directory.

Option	Value	Default	Env	Notes
`--shell`	`bash`, `fish`, `zsh`	Required	None	Selects the shell to install completions for.
`--dir`	path	Shell-specific	None	Destination directory override.

Default completion targets:

Shell	File	Default directory
Bash	`vectron`	`$XDG_DATA_HOME/bash-completion/completions`, fallback `~/.local/share/bash-completion/completions`
Fish	`vectron.fish`	`$XDG_CONFIG_HOME/fish/completions`, fallback `~/.config/fish/completions`
Zsh	`_vectron`	`$XDG_DATA_HOME/zsh/site-functions`, fallback `~/.local/share/zsh/site-functions`