loonghao/vx/vx-commands

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

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

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

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

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

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.

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

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

TOON Format (Token-Optimized)

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

# 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

# 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

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

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

Advanced Execution Syntax

# 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

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

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

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

Cache Management

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

Global Flags

--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.