CLI Reference

Command-line interface for the Wippy runtime.

Global Flags

Available on all commands:

Memory limit priority: --memory-limit flag > GOMEMLIMIT env > 1GB default.

--config may be passed multiple times to compose config files. Files merge left to right: later files override matching values and keep everything else. Every explicitly named file must exist; without --config, the default .wippy.yaml is optional. The first file anchors the directory used to resolve relative paths. Configuration applies in order: file composition, then --profile selections, then --set overrides. See Configuration.

wippy init

Create a new lock file.

wippy init
wippy init --src-dir ./src --modules-dir .wippy

wippy run

Start the runtime or execute a command.

wippy run                                   # Start runtime
wippy run list                              # List available commands
wippy run migrate                           # Run a named custom command
wippy run snapshot.wapp                     # Run from pack file
wippy run acme/http                         # Run module from hub
wippy run acme/http@1.2.3                   # Run specific version
wippy run --exec app:worker                 # Start runtime and execute a single process

Running a hub module (wippy run org/module) resolves it once, records it in wippy.lock, and vendors the verified packs locally. Subsequent runs of the same reference start from the lock — no network needed. A version selector that no longer matches the lock is rejected with a hint to run wippy update.

--set writes any runtime configuration value from the command line, merged over .wippy.yaml per leaf:

wippy run --set cluster.enabled=true \
          --set cluster.membership.join_addrs=node-2:7946,node-3:7946 \
          --set cluster.raft.bootstrap_expect=3

Values coerce by shape: true/false to bool, integers and floats to numbers, everything else stays a string (durations like 5s are parsed where the option expects one).

wippy test

Run the test entrypoint: the process entry declaring the test use case. The runtime boots, executes that entry, and exits. wippy run does not auto-run test entrypoints; testing always goes through wippy test.

wippy test                     # Run tests from the local project
wippy test snapshot.wapp       # Run tests from a pack file
wippy test acme/module@1.2.3   # Run tests from a hub module

wippy lint

Check Lua code for type errors and warnings.

wippy lint
wippy lint --level warning
wippy lint --json
wippy lint --rules

Validates all Lua entries: function.lua, library.lua, process.lua, workflow.lua (including their .bc variants).

wippy add

Add a module dependency.

wippy add acme/http
wippy add acme/http@1.2.3
wippy add acme/http@latest

wippy install

Install dependencies from lock file.

wippy install                            # Install all
wippy install acme/http                  # Install specific module
wippy install --refresh acme/http        # Re-fetch a specific module

wippy update

Update dependencies and regenerate lock file.

wippy update                      # Update all
wippy update acme/http            # Update specific module
wippy update acme/http demo/sql   # Update multiple

wippy pack

Create a snapshot pack (.wapp file).

wippy pack snapshot.wapp
wippy pack release.wapp --description "Release 1.0"
wippy pack app.wapp --embed app:assets --bytecode **

Without --embed or --embed-all, embed patterns fall back to the embed: section of the module manifest wippy.yaml. Packing an application also carries embedded resources from its dependency packs, and only the main module's commands are exposed by the resulting pack.

wippy publish

Publish module to the hub.

wippy publish
wippy publish --version 1.0.0
wippy publish --dry-run

Reads from wippy.yaml in current directory.

The module type is normally declared as type: in wippy.yaml (see Publishing); --module-type overrides it for a single publish. When neither is set, newly created modules default to application with a deprecation warning.

wippy search

Search for modules in the hub.

wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json

wippy auth

Manage registry authentication.

wippy auth login

wippy auth login
wippy auth login --token YOUR_TOKEN

wippy auth logout

wippy auth logout

wippy auth status

wippy auth status
wippy auth status --json

wippy readme

Fetch a module README from the hub.

wippy readme wippy/terminal
wippy readme wippy/terminal@1.2.3
wippy readme --json wippy/terminal@latest

wippy registry

Query and inspect registry entries. Both subcommands accept --profile and --set to shape the merged runtime config the entries are loaded under.

wippy registry list

wippy registry list
wippy registry list --kind "function.lua.*"
wippy registry list --ns "app.*" --json
wippy registry list --meta "type=api" --meta "enabled=true"

Metadata operators for --meta:

wippy registry show

wippy registry show app:http:handler
wippy registry show app:config --yaml

wippy version

Print version information.

wippy version
wippy version --short

Custom Commands

Any process.lua or process.wasm entry can be registered as a named command by adding command metadata:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

Run it with:

wippy run migrate

List all available commands:

wippy run list

Command Metadata Fields

Any process entry kind works (process.lua, process.wasm). The command name must be unique across all loaded entries. Arguments after the command name are passed to the process as string payloads.

Examples

Development Workflow

# Initialize project
wippy init
wippy add wippy/test wippy/llm
wippy install

# Check for errors
wippy lint

# Run with debug output
wippy run -c -v

# Override config for local dev
wippy run -o app:db:host=localhost -o app:db:port=5432

Production Deployment

# Create release pack with bytecode
wippy pack release.wapp --bytecode ** --exclude-ns test.**

# Run from pack with memory limit
wippy run release.wapp -m 2G

Debugging

# Execute single process
wippy run --exec app:worker

# With profiler enabled
wippy run -p -v
# Then: go tool pprof http://localhost:6060/debug/pprof/heap

Dependency Management

# Add new dependency
wippy add acme/http@latest

# Force re-download
wippy install --force

# Update specific module
wippy update acme/http

Publishing

# Login to hub
wippy auth login

# Validate module
wippy publish --dry-run

# Publish
wippy publish --version 1.0.0 --release-notes "Initial release"

Environment Variables

Values in .wippy.yaml may reference OS environment variables with ${env:NAME}, resolved at file load; a missing variable fails config loading. Bare ${name} references resolve from the config's vars: section instead.

Configuration File

Create .wippy.yaml for persistent settings:

logger:
  encoding: console

logmanager:
  min_level: -1  # debug

profiler:
  enabled: true
  address: localhost:6060

override:
  app:gateway:addr: ":9090"
  app:db:host: "localhost"

See Also

• Configuration - Config file reference
• Observability - Monitoring and logging