CLI Reference

Use the Wippy CLI to initialize projects, run the runtime, manage dependencies, inspect registry entries, and publish modules.

This is a command reference. The examples assume an existing project or module when the command operates on source, a lock file, registry entries, or publish metadata; they are not a single end-to-end project.

Global Flags

Available on all commands:

Memory-limit precedence is --memory-limit, then GOMEMLIMIT, then the 1 GB default.

The global --config option 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 publish shadows the global option with a command-local --config <dir> option. For that command, the value is the directory containing wippy.yaml, not a repeatable runtime configuration file.

wippy init

Create wippy.lock, or update its source and module directory settings if it already exists. This command does not scaffold application source files or registry entries.

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.

For a local application, wippy run repairs a stale lock before any runtime service starts. It loads the source dependency declarations, and when the lock already satisfies them it re-resolves the graph from local and installed evidence only (verified-offline access, no network). If that offline resolution matches the lock, boot continues unchanged. If it succeeds but differs, it becomes the candidate graph; the hub is asked to resolve only when the offline pass fails or the lock no longer satisfies the source declarations. Packs the candidate graph is missing are downloaded and verified, and only then is wippy.lock rewritten. A lock that selects a deployment root is authoritative and is never re-resolved.

--exec blocks until the launched process produces its result, then propagates the process exit code as the CLI exit code. Ctrl-C during --exec cancels the running process and the runtime still shuts down gracefully; a second signal forces exit.

--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 are coerced by shape: true and false become booleans, integers and floats become numbers, and other values remain strings. Fields that expect durations parse values such as 5s.

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 source-bearing function.lua, library.lua, process.lua, and workflow.lua entries. Precompiled .bc entries do not contain parseable source and are skipped.

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 artifacts

Work with build-time filesystem artifacts.

wippy artifacts materialize

Validate and materialize one artifact filesystem out of an existing pack.

wippy artifacts materialize snapshot.wapp app:package_fs
wippy artifacts materialize snapshot.wapp app:package_fs --root build

The resource is addressed by its full namespace:name, must declare meta.artifact.format, and that format must be registered in the CLI. The command resolves no module dependencies, does not mutate wippy.lock, invokes no package managers, and takes no part in runtime composition. See Build-time artifacts.

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.

The output file is written atomically: the pack is built into a temporary file in the destination directory, synced, verified, and only then renamed over the target, inheriting the existing file's permissions when one is present. A failed pack leaves the previous file untouched. Naming an output that is also one of the pack's inputs — the same path, or a hard link or symlink resolving to the same file — is refused rather than truncating the input mid-read.

--meta cannot write reserved metadata. The key registry, and anything under the wippy. or system. prefixes, is owned by the pack format and rejected.

Resources declaring meta.artifact.format are validated while packing, so a malformed artifact fails here rather than in a consumer. See Build-time artifacts.

wippy publish

Publish module to the hub.

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

This command reads wippy.yaml from the 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.

Search uses the stored authentication token for the selected registry, when available. Authenticate with wippy auth login to search with your registry identity; --registry selects which registry's credentials are used.

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 control the merged runtime configuration used to load entries.

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
        security:
          actor:
            id: app:migrations
          policies:
            - app.security:migrations
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

Run it with:

wippy run migrate

List all available commands:

wippy run list

wippy run list accepts --profile and --set so the listing reflects the same merged runtime config wippy run would use.

Command Metadata Fields

Any process entry kind works (process.lua, process.wasm). Command names are not checked for uniqueness; when several loaded entries declare the same name, the first match in registry order runs. Arguments after the command name are passed to the process as string payloads.

Command security

A command entry declares the actor and policy scope its CLI launch runs under:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: system.migrations
            meta:
              role: operator
          policies:
            - app.security:migrations_policy
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main

The block lives inside meta.command because it applies only to the CLI launch path — the operator started the command on their own deployment, which is the trust anchor. It has no effect on ordinary spawns of the same process entry; those follow the entry's own security: block.

Declaration is fail-closed and validated before the process starts:

• Unknown fields inside security are rejected.
• An empty security block (no actor, no policies, no groups) is rejected.
• security without a name is rejected — a command must be nameable to be launched.
• A policy or group that cannot be resolved refuses the launch; resolution is atomic, so a partial scope is never installed.

When the block omits actor, the caller's actor is inherited. When it omits both policies and groups, the caller's scope is inherited.

Examples

Development Workflow

# Initialize dependency lock metadata
wippy init
wippy add wippy/test
wippy add 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:
  stream_to_events: true

profiler:
  enabled: true
  address: localhost:6060

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

See Also

• Configuration — Configuration file reference
• Observability — Monitoring and logging