wand

wand is a tiny, cross-platform command runner driven by a simple YAML config file, written in Go. Define your commands and subcommands in a wand.yml, and run them from anywhere in your project tree.

---

🚀 Features

• Simple YAML config: define commands, descriptions, and nested subcommands in a single file.
• Auto-discovery: finds wand.yml by searching the current directory, parent directories, ~/, and ~/.config/.
• Nested subcommands: commands can have arbitrarily deep children.
• Positional arguments: pass arguments to commands and reference them with $1, $2, $@.
• Custom flags: define typed flags (string or bool) with aliases, defaults, and descriptions, accessible as $WAND_FLAG_<NAME> environment variables.
• Environment variables: define env vars globally in .config or per command, with command-level overrides.
• Working directory: override the working directory for any command.
• Aliases: define alternate names for commands.
• Confirmation prompts: require y/N confirmation before running destructive commands.
• Built-in help: auto-generated --help for every command and subcommand.
• Shell execution: runs commands via your $SHELL with proper stdin/stdout/stderr passthrough.

---

🎯 Installation

Download Precompiled Binaries

Grab the latest release for Linux, macOS, or Windows:

• Releases →

Homebrew (macOS/Linux)

Install directly from the tap:

brew install chenasraf/tap/wand

Or tap and then install the package:

brew tap chenasraf/tap
brew install wand

From Source

git clone https://github.com/chenasraf/wand
cd wand
make build

---

✨ Getting Started

Create a wand.yml in your project root:

main:
  description: run the main command
  cmd: echo hello from wand

build:
  description: build the project
  cmd: go build -o myapp

test:
  description: run tests
  cmd: go test -v ./...
  children:
    coverage:
      description: run tests with coverage
      cmd: go test -coverprofile=coverage.out ./...

Run a command

# run the main (default) command
wand

# run a named command
wand build

# run a nested subcommand
wand test coverage

# show help
wand --help
wand test --help

---

📁 Config Resolution

wand searches for wand.yml (or wand.yaml) in the following order:

1. Current working directory (./wand.yml)
2. Parent directories (searching upward to the filesystem root)
3. Home directory (~/.wand.yml)
4. Config directory (~/.config/wand.yml)

The first config file found is used.

You can override config discovery with an explicit path:

# via flag
wand --wand-file ./other-config.yml build

# via environment variable
WAND_FILE=./other-config.yml wand build

The --wand-file flag takes precedence over WAND_FILE.

---

📖 Config Reference

Each top-level key defines a command. The special key main becomes the root (no-argument) command.

Field	Type	Description
description	string	Short description shown in --help
cmd	string	Shell command to execute
children	map[string]Command	Nested subcommands (same structure)
flags	map[string]Flag	Custom flags (see below)
env	map[string]string	Environment variables for this command
working_dir	string	Working directory for the command
aliases	[]string	Alternate names for the command
confirm	bool or string	Prompt for confirmation before running
confirm_default	string	Default answer: "yes" or "no" (default)

Flag fields

Field	Type	Description
alias	string	Single-letter shorthand (e.g. o for -o)
description	string	Description shown in --help
default	any	Default value (string or bool)
type	string	"bool" for boolean flags, omit for string flags

---

📌 Positional Arguments

Commands receive any extra arguments passed on the command line. Use $1, $2, etc. for specific positions, or $@ for all arguments:

greet:
  description: greet someone
  cmd: echo "Hello, $1! You said: $@"

wand greet world foo bar
# → Hello, world! You said: world foo bar

---

🚩 Flags

Define custom flags per command. Flag values are exposed as $WAND_FLAG_<NAME> environment variables (uppercased):

build:
  description: build the project
  cmd: |
    echo "output=$WAND_FLAG_OUTPUT verbose=$WAND_FLAG_VERBOSE"
  flags:
    output:
      alias: o
      description: output path
      default: ./bin
    verbose:
      alias: v
      description: enable verbose output
      type: bool

wand build --output ./dist --verbose
# → output=./dist verbose=true

wand build -o ./dist -v
# → output=./dist verbose=true

wand build
# → output=./bin verbose=false

---

🌍 Environment Variables

Define environment variables globally in .config or per command. Command-level env vars override global ones:

.config:
  env:
    NODE_ENV: production

build:
  description: build the project
  cmd: echo "env=$NODE_ENV out=$OUTPUT_DIR"
  env:
    OUTPUT_DIR: ./dist

wand build
# → env=production out=./dist

---

⚠️ Confirmation Prompts

Add confirm: true for a default prompt, or provide a custom message:

deploy:
  description: deploy to production
  cmd: ./deploy.sh
  confirm: 'Deploy to production?'

clean:
  description: remove all build artifacts
  cmd: rm -rf dist/
  confirm: true

restart:
  description: restart service
  cmd: systemctl restart myapp
  confirm: 'Restart the service?'
  confirm_default: 'yes'

wand deploy
# → Deploy to production? [y/N]

---

🛠️ Contributing

I am developing this package on my free time, so any support, whether code, issues, or just stars is very helpful to sustaining its life. If you are feeling incredibly generous and would like to donate just a small amount to help sustain this project, I would be very very thankful!

I welcome any issues or pull requests on GitHub. If you find a bug, or would like a new feature, don’t hesitate to open an appropriate issue and I will do my best to reply promptly.

---

📜 License

wand is licensed under the CC0-1.0 License.