Vx Project

Project management guide for vx. Use when setting up a new project, configuring vx.toml, or managing project-level tool versions and scripts.

Security Scan

This is an instruction-only project guide for the vx CLI that is internally consistent with its stated purpose and does not request extra credentials or install steps.

Purpose & Capability

The name and description match the SKILL.md contents: guidance for creating and managing vx.toml, running vx commands, and handling project tools and scripts. The skill does not request unrelated binaries, env vars, or secrets.

Instruction Scope

Runtime instructions are limited to calling vx commands and reading common project files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.). The doc also mentions hooks and templates which, when executed by vx, may run arbitrary scripts from the project—this is expected for a project-management tool but is the primary operational risk to be aware of.

Install Mechanism

No install spec or code files are provided (instruction-only). Nothing is downloaded or written by the skill itself, so there is minimal installation risk from the skill bundle.

Credentials

The skill declares no required environment variables or credentials. The SKILL.md merely shows examples of how vx can be configured to read env vars (e.g., API_KEY, DATABASE_URL) which is consistent and does not imply exfiltration by the skill itself.

Persistence & Privilege

always is false and the skill is user-invocable. It does not request persistent or elevated platform privileges and does not instruct modifying other skills or global agent settings.

Assessment

This skill is a documentation-only guide for using the vx CLI and appears coherent. Before running vx setup/sync/dev on untrusted code: 1) ensure you have an authentic vx CLI from a trusted source; 2) inspect vx.toml, vx.lock, and any hooks or templates (post_setup, pre_commit, templates' post_setup.sh) because those can run arbitrary commands and install packages; 3) avoid placing secrets (API keys, DB URLs) directly in vx.toml or commit them to repos; 4) prefer pinned versions and review vx.lock for CI reproducibility; and 5) run initial setup in a sandboxed environment or CI runner with least privilege if the repository is untrusted.

VX Project Management Guide

Quick start: Run vx init to create vx.toml, vx setup to install all tools, vx dev to enter the dev environment. For existing projects, just run vx setup after cloning.

Project Setup

Initialize a Project

vx init                     # Create vx.toml interactively
vx init --template node     # Use a template
vx init --minimal           # Create minimal vx.toml

Project Detection

vx automatically detects project types and suggests tools:

vx analyze                  # Analyze project (detects languages, dependencies)
vx analyze --json           # JSON output for AI parsing

Detected ecosystems: Node.js, Python, Rust, Go, Java, .NET, C/C++, Zig Detected frameworks: React, Vue, Angular, Next.js, Nuxt, Svelte, Django, Flask, FastAPI, Tauri, Electron, React Native, NW.js, and more Detected package managers: npm, yarn, pnpm, bun, pip, uv, cargo, go modules

The project analyzer reads indicator files like package.json, pyproject.toml, Cargo.toml, go.mod, etc. to suggest the right tools.

vx.toml Configuration

Basic Structure

# vx.toml - Project tool configuration

[tools]
# Version constraints
node = "22"                 # Major version (any 22.x.x)
go = "1.22"                 # Minor version (any 1.22.x)
uv = "latest"               # Always use latest
rust = "1.80"               # Specific version
just = "*"                  # Any version

# Platform-specific tools
[tools.msvc]
version = "14.42"
os = ["windows"]            # Only install on Windows

[tools.brew]
version = "latest"
os = ["macos", "linux"]

[scripts]
# Development scripts
dev = "npm run dev"
test = "cargo test"
lint = "npm run lint && cargo clippy"
build = "just build"

# CI/CD scripts
ci = "just ci"
release = "just release"

[hooks]
# Lifecycle hooks
pre_commit = ["vx run lint"]
post_setup = ["npm install", "cargo fetch"]

Version Constraints

Constraint	Example	Meaning
Exact	"1.2.3"	Only version 1.2.3
Major	"1"	Any 1.x.x
Minor	"1.2"	Any 1.2.x
Latest	"latest"	Always latest
Any	"*"	Any available version
Range	">=1.0.0 <2.0.0"	Range constraint

Platform-Specific Tools

[tools]
# Cross-platform tools
node = "22"
uv = "latest"

# Windows-only
[tools.msvc]
version = "14.42"
os = ["windows"]

# macOS/Linux only
[tools.brew]
version = "latest"
os = ["macos", "linux"]

Project Commands

Setup & Sync

vx setup                    # Full project setup (sync + hooks)
vx sync                     # Install all tools from vx.toml
vx sync --clean             # Remove unlisted tools
vx sync --check             # Check without installing

Running Scripts

vx run dev                  # Run development server
vx run test                 # Run tests
vx run build                # Build project
vx run --list               # List available scripts

Lock File

vx lock                     # Generate vx.lock
vx lock --update            # Update locked versions
vx lock --check             # Verify lock file

The vx.lock file ensures reproducible builds:

# vx.lock - Auto-generated, do not edit
[tools]
node = { version = "22.0.0", checksum = "sha256:..." }
go = { version = "1.22.0", checksum = "sha256:..." }

Environment Management

Project Environment

vx dev                      # Enter project environment
vx env list                 # List environments
vx env activate             # Print activation commands
eval $(vx env activate)     # Activate in shell

Environment Variables

Define in vx.toml:

[env]
NODE_ENV = "development"
DATABASE_URL = "postgresql://localhost:5432/dev"
API_KEY = { env = "API_KEY", required = true }

Dependency Management

Add/Remove Tools

vx add node@22              # Add tool to vx.toml
vx add go rust uv           # Add multiple tools
vx remove node              # Remove tool from vx.toml

Check Constraints

vx check                    # Verify tool constraints
vx check --json             # JSON output
vx check --fix              # Auto-fix issues

Multi-Package Projects

Monorepo Support

For monorepos, create vx.toml in root:

# Root vx.toml
[tools]
node = "22"
pnpm = "latest"

[scripts]
install = "pnpm install"
build = "pnpm -r build"
test = "pnpm -r test"

Workspace Packages

Individual packages can have their own vx.toml:

# packages/backend/vx.toml
[tools]
go = "1.22"

[scripts]
dev = "go run ./cmd/server"

Best Practices

1. Version Pinning

Pin versions for CI/CD:

[tools]
node = "22.0.0"             # Exact version for CI

2. Lock Files

Always commit vx.lock:

git add vx.lock

3. Scripts Organization

Group related scripts:

[scripts]
# Development
dev = "..."
watch = "..."

# Testing
test = "..."
test:watch = "..."

# Build
build = "..."
build:prod = "..."

4. Hooks for Quality

Use hooks for automated checks:

[hooks]
pre_commit = ["vx run lint", "vx run test"]
post_checkout = ["vx sync"]

Project Templates

Create reusable templates:

# Create template from current project
vx template create my-template

# Use template
vx init --template my-template

Template Structure

~/.vx/templates/my-template/
├── vx.toml
├── .gitignore
├── README.md
└── hooks/
    └── post_setup.sh