VX Command Reference#

Quick rule: Prefer semantic reduction first: --json with selected fields, then --jq/ vx rg filtering, then --compact for broad logs. Set VX_OUTPUT=json, VX_OUTPUT=toon, or VX_OUTPUT=compact only when you want that default for the whole invocation.

Structured Output Commands (AI-Optimized)#

vx-native commands support --json, --toon, --compact, and --output-format <text|json|toon|compact>. Forwarded tools such as vx git, vx gh, vx cargo, or vx npm keep their native stdout by default; use the tool's own structured flags first, or add vx --compact ... when broad subprocess output must be filtered.

Project Analysis#

bash

vx analyze --json           # Analyze project structure
vx check --json             # Verify tool constraints
vx ai context --json        # Generate AI-friendly project context

Output fields (analyze):

• ecosystems[] - Detected ecosystems (nodejs, python, rust, go)
• dependencies[] - Project dependencies
• scripts[] - Available scripts
• required_tools[] - Tools needed

Output fields (check):

• requirements[] - Tool requirement status
• all_satisfied - Whether all constraints are met
• missing_tools[] - Tools that need installation

Output fields (ai context):

• project - Project info (name, languages, frameworks)
• tools[] - Installed tools with versions
• scripts[] - Available scripts
• constraints[] - Tool constraints

Tool Management#

bash

vx list --json              # List installed tools
vx versions node --json     # List available versions
vx which node --json        # Find tool location
vx search <query> --json    # Search for tools

Output fields (list):

• runtimes[] - Available runtimes
• total - Total count
• installed_count - Installed count

Output fields (versions):

• versions[] - Available versions with metadata
• latest - Latest version
• lts - LTS version (if applicable)

Output fields (which):

• path - Executable path
• version - Resolved version
• source - Source (vx, system, global_package)

Installation#

bash

vx install node@22 --json   # Install tool
vx sync --json              # Sync from vx.toml

Output fields (install):

• runtime - Runtime name
• version - Installed version
• path - Installation path
• duration_ms - Installation duration
• dependencies_installed[] - Dependencies also installed

Output fields (sync):

• installed[] - Successfully installed
• skipped[] - Skipped (already installed)
• failed[] - Failed installations
• duration_ms - Total duration

AI Integration#

bash

vx ai context               # Generate AI-friendly context (Markdown)
vx ai context --json        # JSON format
vx ai context --minimal     # Minimal output
vx ai session init          # Initialize session state
vx ai session status        # Show session status
vx ai session cleanup       # Clean up session

Environment#

bash

vx env --json               # Show environment variables
vx dev --export             # Export shell environment

Managed Command Shims#

Check vx --version and vx --help first. If shim is listed, inspect vx shim --help and vx shim add --help for this interface; v0.9.34 does not include it. Do not probe an unknown subcommand as a runtime on older builds.

bash

vx shim path                         # Default targets and their PATH status
vx shim list --json                   # Recorded names, targets, launcher, directories, files
# After checking name conflicts and every destination file:
vx shim add jq --as jq-vx --dir "/absolute/path/to/shim-bin"
vx shim remove jq-vx                  # Remove by exposed name, not runtime spec

--dir is repeatable and replaces the defaults; use absolute paths so later sync/ remove do not depend on the working directory. Without it, add writes to both the vx bin directory and the directory containing the current vx executable (deduplicated). Adding a shim does not install its target or edit PATH.

After upgrading or moving vx, use vx shim sync only after checking ownership of every registered destination: it rewrites all entries, including existing files. --force is an explicit overwrite decision, never the default repair. For Codex targets, shell-specific resolution, conflicts, and safe removal, read the managed command shim guide. There is no vx shim rebuild or vx shim codex form in this interface.

Output Formats#

JSON Format#

bash

vx list --json
# Output: {"runtimes": [...], "total": 50, "installed_count": 5}

TOON Format (Token-Optimized)#

bash

vx list --output-format toon
vx list --toon
# Output:
# runtimes[50]{name,installed,description}:
#   node,true,Node.js runtime
#   python,false,Python runtime
#   ...

TOON format is recommended for AI agents - it saves 40-60% tokens compared to JSON.

Compact Format and Forwarded Logs#

bash

# vx-native compact summary
vx --compact list node
vx list --output-format compact

# Forwarded subprocess filtering
vx --compact gh run view 789 --log
vx --compact --filter-level aggressive cargo test

Compact mode is RTK-inspired: it strips ANSI noise, collapses repeated lines, keeps error-looking lines, and enforces a line budget for subprocess output. Use it after semantic options like gh --json --jq or vx rg filters.

GitHub and CI Triage#

bash

# Smallest useful status view
vx gh run view 789 --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'

# Failure search with capped matches
vx gh run view 789 --log | vx rg -n -m 80 "error|failed|panic|Traceback|FAILED|warning"

# Broad fallback without raw-log token cost
vx --compact gh run view 789 --log

Do not rely on default vx gh or vx git output to save tokens. Their default behavior is transparent forwarding; savings come from selected fields, --jq, search filters, or explicit --compact.

Environment Variable#

bash

export VX_OUTPUT=json       # Default to JSON output
export VX_OUTPUT=toon       # Default to TOON output
export VX_OUTPUT=compact    # Default to compact output/filtering
export VX_FILTER_LEVEL=normal  # light, normal, aggressive

Command Groups#

Tool Execution#

bash

vx <tool> [args...]         # Run any tool
vx npm install              # Run npm
vx cargo build              # Run cargo

Advanced Execution Syntax#

bash

# Runtime with version
vx node@22 app.js                     # Use specific Node.js version

# Runtime executable override
vx msvc@14.42::cl main.cpp            # Run cl from MSVC runtime

# Package execution (ecosystem:package pattern)
vx npm:vite                            # Run vite via npm
vx uv:ruff check .                    # Run ruff via uv
vx npm:typescript@5.0::tsc            # Run tsc from specific typescript version

# Package aliases (shortcuts)
vx vite                                # Same as: vx npm:vite
vx meson                              # Same as: vx uv:meson

# Multi-runtime composition
vx --with bun@1.1 --with deno node app.js   # Multiple runtimes in PATH

Tool Management#

bash

vx install <tool>@<version> # Install tool
vx uninstall <tool>         # Uninstall tool
vx list                     # List tools
vx versions <tool>          # Show versions
vx which <tool>             # Find tool path
vx switch <tool>@<version>  # Switch version

Project Management#

bash

vx init                     # Initialize vx.toml
vx add <tool>               # Add tool to project
vx remove <tool>            # Remove tool from project
vx sync                     # Sync tools from vx.toml
vx lock                     # Generate vx.lock
vx check                    # Check constraints

Script Execution#

bash

vx run <script>             # Run script from vx.toml
vx run --list               # List available scripts

Cache Management#

bash

vx cache dir                # Show cache directory
vx cache clean              # Clean cache

Global Flags#

bash

--json                      # JSON output
--toon                      # TOON output
--compact, -u               # Compact RTK-style output / subprocess filter
--output-format <text|json|toon|compact>   # Output format
--fields <a,b,c>            # Field mask for JSON-capable vx commands
--filter-level <light|normal|aggressive>   # Compact subprocess filter level
--verbose                   # Verbose output
--debug                     # Debug output
--use-system-path           # Use system PATH
--cache-mode <mode>         # Cache mode (normal, refresh, offline, no-cache)

Exit Codes#

• 0 - Success
• 1 - General error
• 2 - Tool not found
• 3 - Installation failed
• 4 - Version not found
• 5 - Network error
• 6 - Permission error
• 7 - Configuration error

---

Delivery Surface — External Systems Are Evidence#

GitHub PRs, CI runs, and dashboards are supporting evidence, not the delivery surface. The conclusion has to land where the work is tracked.

• Record the outcome once, completely — one issue comment carrying status, branch/commit/PR, what you validated, the blocker, and the next owner.
• Verify terminal state, not intermediate state. A green CI run or an open, review-ready PR is not "shipped". Confirm merged / released / deployed, then record that.
• Keep public surfaces public-safe. PR titles, bodies, and commit messages carry technical content only — no internal issue IDs, routing history, reviewer handoffs, local absolute paths, or internal hostnames.
• Collect results in the foreground. A queued or pending state is a handoff, not a completion; never end a turn "standing by" for background work.

Concretely: the delivery surface is the team's issue or task tracker — the issue comment plus its metadata. A PR comment alone delivers nothing.