Vex

Vex turns scripts and task files into clean, validated, distributable CLIs.

---

Overview

Vex is a small, fast, single-binary CLI tool that:

• Wraps scripts and tasks with typed CLI flags
• Validates dependencies before execution
• Generates standalone executables
• Supports nested subcommands via workspaces
• Groups many tools into one cohesive binary
• Automatic Environment File Loading (e.g., .env)
• Version Pinning (e.g., .vex-version)
• Groups many tools into one cohesive binary

Supported runtimes: bash, python, make, just

Documentation

Full documentation is available in the docs/ directory:

• 🚀 Getting Started: Installation and quick start guide.
• ⚙️ Configuration Reference: YAML schemas for Components and Workspaces.
• 🗂️ Workspaces: How to build nested CLIs and standalone apps.
• 🛡️ Dependencies Tooling: Executable, Python, and Environment validation.
• 🧠 Architecture & Mechanisms: Deep dive into how Vex works under the hood.
• 💻 CLI Reference: Auto-generated command-line documentation.

Quick Start

1. Create a component config (hello.yaml)

command: hello
runtime: bash
script: hello.sh
args:
  - name: name
    type: string
    required: true
    help: "Name to greet"

2. Write your script (hello.sh)

#!/bin/bash
echo "Hello, $VEX_ARG_NAME!"

3. Run it

vex run hello.yaml --name World
# Output: Hello, World!

4. Advanced Features

Environment Files: Vex automatically loads a .env file found in the current working directory of the caller. You can override this using the --env-file flag when running commands:

vex run hello.yaml --env-file custom.env --name World

Version Pinning: Ensure execution consistency across your team and CI pipelines by defining a .vex-version file in your repository. Vex warns on version mismatches between the executing binary and the pinned version, and can fail strictly in CI environments:

vex run hello.yaml --strict-version --name World

Examples

See the examples/ directory:

• hello — minimal bash component
• resize — python component with multiple typed args
• synapse — workspace with nested subcommands and an init script
• deps — dependencies validation component
• envbind — example of mapping argument values from environment variables
• make-just-workspace — executing Make and Just file targets

Project Structure

cmd/               # CLI commands (Cobra)
pkg/
  config/          # YAML config parsing and validation
  executor/        # Argument parsing and execution orchestration
  runtime/         # Runtime adapters (bash, python)
  builder/         # Standalone binary generation
  workspace/       # Dynamic tree generation for Workspaces
  dependency/      # Validation rules and hints
examples/          # Example components
docs/              # Extensive documentation

License

MIT