CLI Reference

Command-line interface for the Wippy runtime.

Global Flags

Available on all commands:

Flag Short Description
--config Config file (default: .wippy.yaml)
--verbose -v Enable debug logging
--very-verbose Debug with stack traces
--console -c Colorful console logging
--silent -s Disable console logging
--event-streams -e Stream logs to event bus
--profiler -p Enable pprof on localhost:6060
--memory-limit -m Memory limit (e.g., 1G, 512M)

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

wippy init

Create a new lock file.

wippy init
wippy init --src-dir ./src --modules-dir .wippy
Flag Short Default Description
--src-dir -d ./src Source directory
--modules-dir .wippy Modules directory
--lock-file -l wippy.lock Lock file path

wippy run

Start the runtime or execute a command.

wippy run                                    # Start runtime
wippy run list                               # List available commands
wippy run test                               # Run tests
wippy run snapshot.wapp                      # Run from pack file
wippy run acme/http                          # Run module
wippy run --exec app:processes/app:worker   # Execute single process
Flag Short Description
--override -o Override entry values (namespace:entry:field=value)
--exec -x Execute process and exit (host/namespace:entry)
--host Host for execution
--registry Registry URL

wippy lint

Check Lua code for type errors and warnings.

wippy lint
wippy lint --level warning

Validates all Lua entries: function.lua.*, library.lua.*, process.lua.*, workflow.lua.*.

Flag Description
--level Minimum severity level to report

wippy add

Add a module dependency.

wippy add acme/http
wippy add acme/http@1.2.3
wippy add acme/http@latest
Flag Short Default Description
--lock-file -l wippy.lock Lock file path
--registry Registry URL

wippy install

Install dependencies from lock file.

wippy install
wippy install --force
Flag Short Description
--lock-file -l Lock file path
--force Bypass cache, always download
--registry Registry URL

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
Flag Short Default Description
--lock-file -l wippy.lock Lock file path
--src-dir -d . Source directory
--modules-dir .wippy Modules directory
--registry Registry URL

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 **
Flag Short Description
--lock-file -l Lock file path
--description -d Pack description
--tags -t Pack tags (comma-separated)
--meta Custom metadata (key=value)
--embed Embed fs.directory entries (patterns)
--list List fs.directory entries (dry-run)
--exclude-ns Exclude namespaces (patterns)
--exclude Exclude entries (patterns)
--bytecode Compile Lua to bytecode (** for all)

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.

Flag Description
--version Version to publish
--dry-run Validate without publishing
--label Version label
--release-notes Release notes
--registry Registry URL

Search for modules in the hub.

wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json
Flag Description
--json Output as JSON
--limit Maximum results
--registry Registry URL

wippy auth

Manage registry authentication.

wippy auth login

wippy auth login
wippy auth login --token YOUR_TOKEN
Flag Description
--token API token
--registry Registry URL
--local Store credentials locally

wippy auth logout

wippy auth logout
Flag Description
--registry Registry URL
--local Remove local credentials

wippy auth status

wippy auth status
wippy auth status --json

wippy registry

Query and inspect registry entries.

wippy registry list

wippy registry list
wippy registry list --kind function.lua
wippy registry list --ns app --json
Flag Short Description
--kind -k Filter by kind
--ns -n Filter by namespace
--name Filter by name
--meta Filter by metadata
--json Output as JSON
--yaml Output as YAML
--lock-file -l Lock file path

wippy registry show

wippy registry show app:http:handler
wippy registry show app:config --yaml
Flag Short Description
--field -f Show specific field
--json Output as JSON
--yaml Output as YAML
--raw Raw output
--lock-file -l Lock file path

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: test_runner
    kind: process.lua
    meta:
      command:
        name: test
        short: Run application tests
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

Run it with:

wippy run test

List all available commands:

wippy run list

Command Metadata Fields

Field Required Description
name Yes Command name used with wippy run <name>
short No Short description shown in wippy run list

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.

Examples

Development Workflow

# Initialize project
wippy init
wippy add wippy/http wippy/sql
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:processes/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"

Configuration File

Create .wippy.yaml for persistent settings:

logger:
  mode: development
  level: debug
  encoding: console

logmanager:
  min_level: -1  # debug

profiler:
  enabled: true
  address: localhost:6060

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

See Also