Skip to content

command-reference.md

Latest commit

 

History

History
677 lines (469 loc) · 10.6 KB

command-reference.md

File metadata and controls

677 lines (469 loc) · 10.6 KB

Command Reference

This guide is the release-ready CLI reference for vex.

It is based on the current command surface exposed by vex --help and the clap definitions in src/cli/.

Use it when you want the full command map in one place without jumping between README sections.

Quick Rules

  • Tool specs use the form tool@version, for example node@20, go@1.24, or python@3.12.8.
  • The built-in tool names are node, go, java, rust, and python.
  • vex supports both project-local version files and global defaults in ~/.vex/tool-versions.
  • Commands that support JSON output use --json.
  • Use vex help <command> or vex <command> --help for the in-terminal help view.

Top-Level Commands

vex init
vex install
vex sync
vex use
vex relink
vex list
vex list-remote
vex current
vex uninstall
vex env
vex local
vex global
vex lock
vex upgrade
vex outdated
vex prune
vex alias
vex exec
vex run
vex doctor
vex repair
vex self-update
vex tui
vex python
vex rust

Setup and Bootstrapping

vex init

Initialize ~/.vex, configure shell integration, or bootstrap a project template.

Usage:

vex init [--shell <shell>]
vex init --list-templates
vex init --template <template>
vex init --template <template> --dry-run
vex init --template <template> --add-only

Options:

  • --shell <shell>
    • valid values: auto, zsh, bash, fish, skip
  • --template <template>
    • initialize the current directory with an official template
  • --list-templates
    • print the available built-in templates
  • --dry-run
    • preview template changes without writing files
  • --add-only
    • merge only safe files such as .tool-versions and .gitignore, then create missing starter files

Examples:

vex init --shell auto
vex init --list-templates
vex init --template rust-cli
vex init --template python-venv --add-only

vex env

Print the generated shell hook for auto-switching.

Usage:

vex env <shell>
vex env <shell> --exports

Arguments:

  • <shell>
    • zsh, bash, fish, or nu

Examples:

vex env zsh
vex env fish
vex env nu

Notes:

  • vex env <shell> prints the long-lived shell hook you add to your shell config.
  • vex env <shell> --exports prints the current directory's resolved export/unset block and is primarily used internally by the shell hook.

vex doctor

Run health checks for the current installation.

The report includes core PATH/symlink checks, managed npm global bin checks, and active PATH conflicts from other tool managers that can shadow vex.

Usage:

vex doctor
vex doctor --json
vex doctor --verbose

Options:

  • --json
    • print machine-readable diagnostics
  • --verbose
    • include extra provenance and captured-environment details in text output

vex repair

Preview or apply safe legacy home-directory migrations into ~/.vex.

Usage:

vex repair migrate-home
vex repair migrate-home --tool <tool>
vex repair migrate-home --apply

Examples:

vex repair migrate-home
vex repair migrate-home --tool rust
vex repair migrate-home --apply

Tool Installation and Switching

vex install

Install one or more tool specs, or install from version files when no spec is provided.

Usage:

vex install [spec...]
vex install --from <source>
vex install --frozen

Options:

  • --no-switch
    • install without automatically activating the new version
  • --force
    • reinstall even if the version already exists
  • --from <source>
    • install from a version file, vex-config.toml, HTTPS URL, or Git repository
  • --frozen
    • require .tool-versions.lock and fail if the lockfile is missing or out of sync
  • --offline
    • use only cached metadata and archives

Examples:

vex install node@20
vex install node@20 go@1.24
vex install python@3.12 --no-switch
vex install node@20 --force
vex install --from vex-config.toml
vex install --frozen
vex install node@20 --offline

vex sync

Install missing versions from the current managed context.

Usage:

vex sync
vex sync --from <source>
vex sync --frozen

Options:

  • --from <source>
    • sync from a version file, vex-config.toml, HTTPS URL, or Git repository
  • --frozen
    • strictly enforce .tool-versions.lock
  • --offline
    • use only cached data

Examples:

vex sync
vex sync --from https://company.example/vex-config.toml
vex sync --frozen
vex sync --offline

vex use

Switch the current active version for a tool, or auto-resolve from version files.

Usage:

vex use <spec>
vex use --auto

Options:

  • --auto
    • read version files such as .tool-versions, .node-version, or .python-version

Examples:

vex use node@22
vex use python@3.12
vex use --auto

vex relink

Rebuild managed binary links for the active toolchain.

Usage:

vex relink <tool>

Notes:

  • currently only node is supported
  • use this after npm install -g <package> adds a new executable to the active Node toolchain
  • it only rebuilds links under ~/.vex/bin; it does not install packages or change shell configuration

Examples:

vex relink node

vex local

Write a tool pin into the current directory's .tool-versions.

Usage:

vex local <spec>

Example:

vex local node@20.11.0

vex global

Write a global default version into ~/.vex/tool-versions.

Usage:

vex global <spec>

Example:

vex global go@1.24

vex uninstall

Remove an installed toolchain version.

Usage:

vex uninstall <spec>

Example:

vex uninstall node@20.11.0

Rust Extensions

vex rust

Manage official Rust targets and components for the active Rust toolchain.

Usage:

vex rust target list
vex rust target add <name>...
vex rust target remove <name>...
vex rust component list
vex rust component add <name>...
vex rust component remove <name>...

Examples:

vex rust target add aarch64-apple-ios aarch64-apple-ios-sim
vex rust component add rust-src

vex lock

Generate .tool-versions.lock from the current managed context.

Usage:

vex lock

Example:

vex lock

Inspection and Discovery

vex list

List locally installed versions for one tool.

Usage:

vex list <tool>
vex list <tool> --json

Example:

vex list node
vex list python --json

vex list-remote

List available upstream versions.

Usage:

vex list-remote <tool>
vex list-remote <tool> --filter <filter>

Options:

  • --filter, -f
    • valid values: all, lts, major, latest
  • --no-cache
    • bypass the remote-version cache
  • --offline
    • use only cached remote data
  • --json
    • print machine-readable output

Examples:

vex list-remote node
vex list-remote node --filter lts
vex list-remote node --filter major --no-cache
vex list-remote python --json
vex list-remote node --offline

vex current

Show active versions in the current environment.

Usage:

vex current
vex current --json

Upgrades, Drift, and Cleanup

vex upgrade

Install and switch to the latest version of one tool, or upgrade the whole managed context.

Usage:

vex upgrade <tool>
vex upgrade --all

Options:

  • --all
    • upgrade every managed tool in the current context

Examples:

vex upgrade node
vex upgrade --all

vex outdated

Show which managed tools are behind the latest available version.

Usage:

vex outdated
vex outdated <tool>
vex outdated --json

Examples:

vex outdated
vex outdated python
vex outdated --json

vex prune

Remove unused caches, stale locks, and unreferenced toolchains.

Usage:

vex prune
vex prune --dry-run

Options:

  • --dry-run
    • preview removals without deleting anything

Alias:

  • vex gc
    • exact alias for vex prune

Examples:

vex prune --dry-run
vex gc

Alias Management

vex alias is a command group. There is no vex alias <tool> shortcut.

vex alias set

Create a user-defined alias for one tool version.

Usage:

vex alias set <tool> <alias> <version> [--project]

Options:

  • --project
    • store the alias in .vex.toml instead of ~/.vex/aliases.toml

Examples:

vex alias set node production 20.11.0
vex alias set node lts-current 20.11.0 --project

vex alias list

List aliases globally, per project, or for one tool.

Usage:

vex alias list
vex alias list [tool]

Options:

  • --project
    • show only project aliases
  • --global
    • show only global aliases

Examples:

vex alias list
vex alias list node
vex alias list --project

vex alias delete

Remove an alias.

Usage:

vex alias delete <tool> <alias> [--project]

Examples:

vex alias delete node production
vex alias delete node lts-current --project

Project-Aware Execution

vex exec

Run one command inside the resolved vex environment without changing global symlinks.

Usage:

vex exec -- <command> [args...]

Examples:

vex exec -- node -v
vex exec -- python -m pytest
vex exec -- cargo test

vex run

Run a named task from [commands] in .vex.toml.

Usage:

vex run <task> [args...]

Examples:

vex run test
vex run lint
vex run dev -- --host 0.0.0.0

Python Workflow Commands

vex python currently accepts a single subcommand word rather than nested clap subcommands.

Supported values:

  • init
    • create .venv using the active vex-managed Python and record that version in .tool-versions
  • freeze
    • run pip freeze and write requirements.lock
  • sync
    • create .venv if needed and restore dependencies from requirements.lock

Usage:

vex python init
vex python freeze
vex python sync

Recommended workflow:

vex install python@3.12
cd my-project
vex python init
pip install requests flask
vex python freeze
vex python sync

Interactive and Self-Management Commands

vex tui

Launch the interactive terminal dashboard.

Usage:

vex tui

Notes:

  • requires an interactive terminal
  • intended for current-version overview, health warnings, disk usage, and quick actions

vex self-update

Download and install the latest published vex release for the current architecture.

Usage:

vex self-update

Help Commands

Use any of these when you want the built-in CLI help:

vex --help
vex help
vex help install
vex install --help
vex alias --help

Related Guides