vfox Documentation

vfox is a cross-platform, extensible universal version manager for Windows (native) and Unix-like systems (Linux, macOS). It allows you to quickly install and switch between different development environments and runtime versions.

Key features include:

• Flexible version scopes: Manage versions at the Project-level, Session-level, or Global level.
• Automatic switching: Automatically switches to the appropriate tool version when entering a project directory.
• Configuration sharing: Saves tool version information in a .vfox.toml file, which can be shared across projects to ensure team consistency.
• Compatibility: Supports existing version files like .node-version, .nvmrc, and .sdkmanrc.
• Extensibility: Uses a simple plugin interface to support any language or tool.

The vfox plugin registry is a public repository used to collect and distribute plugins. Users can install plugins via vfox add <plugin-name>. The registry consists of two main directories:

• plugins: Stores the manifest.json files for each plugin, named by the plugin's short name (e.g., nodejs.json).
• sources: Stores the source information for each plugin manifest, also named by the plugin's short name (e.g., nodejs.json).

The registry automatically retrieves the latest version information and verifies plugin availability every hour using the information in the sources directory.

To permanently delete all installed SDK versions, plugins, configuration files, and the global .vfox.toml file, remove the vfox data directory:

rm -rf ~/.version-fox

Warning: This action is irreversible and will delete all SDK versions managed by vfox.

To publish a plugin to the public registry, follow these steps:

1. Create the plugin: Follow the plugin creation guide.
2. Maintain a manifest.json: Ensure your plugin has a manifest.json file describing its version and metadata. If using the vfox-plugin-template, this is generated automatically upon release.
3. Create a source file: Create a JSON file in the sources/ directory of the registry repository using the plugin's short name (e.g., sources/nodejs.json).
4. Configure the source file: Add the plugin's manifest URL and optional test configuration to the source file.
5. Submit a PR: Submit a Pull Request to the vfox-plugins repository.

Once the PR is merged, the plugin is added to the public registry and its status is checked hourly.

For non-interactive environments like Docker build steps, CI jobs, or other non-interactive shells, do not rely on vfox activate as shell hooks are typically intended for interactive shells and may not trigger. Instead, use vfox exec to run commands immediately with the correct SDK environment.

Use vfox use only when you want to persist version selection for Global, Project, or Session scope.

vfox exec nodejs@24.14.0 -- npm install -g pnpm
vfox exec nodejs@24.14.0 -- bash -lc 'node -v && npm -v'

A vfox plugin must follow a specific directory structure to be recognized and function correctly:

• metadata.lua: Contains basic plugin information (name, version, etc.).
• hooks/: Directory for hook functions. Each hook function must correspond to exactly one .lua file (e.g., hooks/available.lua).
• lib/: Directory for dependent libraries. vfox automatically loads all .lua files in this directory. Files in other directories will not be loaded.
• README.md: Plugin documentation.
• LICENSE: Plugin license.

To simplify development, you can use the vfox-plugin-template.

The json library (based on gopher-json) provides functions to encode Lua tables into JSON strings and decode JSON strings back into Lua tables. Use require("json") to load the library.

local json = require("json")

local obj = { "a", 1, "b", 2, "c", 3 }
local jsonStr = json.encode(obj)
local jsonObj = json.decode(jsonStr)

-- Verify equality
for i = 1, #obj do
    assert(obj[i] == jsonObj[i])
end

Once vfox is installed and activated, you can manage language runtimes using the following workflow:

1. Add a plugin for the language you want to use (e.g., nodejs):

   vfox add nodejs

2. Install a specific version of the runtime:

   vfox install nodejs@21.5.0

3. Switch to the installed version:

   vfox use nodejs@21.5.0

4. Verify the version:

   node -v