wendy run
Build and run application on a WendyOS device
Syntax
wendy run [flags]Examples
wendy run
wendy run --watch
wendy run --device my-robot
wendy run --detachArguments
No positional arguments are declared in the command synopsis.
Flags
Flags below include inherited options. Types and defaults come from the CLI source. An empty default means no value is configured.
| Flag | Type | Default | Description |
|---|---|---|---|
--build-host | string | (empty) | Build on another WendyOS device; omit the device to open a picker, or use --build-host=DEVICE Value when used without an argument: " ". |
--build-type | string | (empty) | Build type to use when Dockerfile/Containerfile is present alongside Package.swift or Python project markers: docker, swift, or python |
--builder | string | (empty) | Image builder to force for Dockerfile/Containerfile builds: docker, apple-container, or buildkit |
--chunking | string | auto | Content-defined chunking (CBC) deploy path: auto (try chunk-diff, fall back to registry push), force (chunk-diff only, no fallback), or off (registry push only) |
--debounce | int | 400 | Watch mode (--watch): quiet period in milliseconds after the last change before redeploying |
--debug | bool | false | Enable debug logging |
--deploy | bool | false | Create container but do not start it |
--detach | bool | false | Start container and return without streaming logs, waiting for readiness, or opening the app URL |
--device | string | (empty) | Target device hostname; wendy run accepts a comma-separated list to deploy one build to several devices (needs a remote build host and --detach). Defaults to $WENDY_DEVICE, then the saved default device |
--dockerfile | string | (empty) | Build file to build from: a Dockerfile, Containerfile, or Stagefile (e.g. Dockerfile.prod, Containerfile, prod.stagefile.yaml); shows a selection menu when multiple build files exist |
--env | stringArray | [] | Set an environment variable in the container as KEY=VALUE; repeatable, and overrides wendy.json env of the same key |
--gpu-arch | string | (empty) | GPU architecture a Stagefile cuda: stage targets (sm_87); read from the device when one is selected |
--hil | string | (empty) | Run hardware in the loop; omit the device to open a cloud picker, or use --hil=DEVICE Value when used without an argument: " ". |
--json | bool | false | Output in JSON format |
--keep-going | bool | false | Multi-service: deploy services that build successfully instead of aborting the whole group on the first build/push failure |
--max-concurrency | int | 0 | Multi-service/Compose: max service images to build+push at once (0 = default limit of 4) |
--no-restart | bool | false | Do not restart on exit |
--prefix | string | (empty) | Project directory to run from instead of the current working directory |
--product | string | (empty) | Swift Package Manager product to build and run |
--restart-on-failure | bool | false | Restart on failure |
--restart-unless-stopped | bool | false | Restart unless manually stopped |
--service | string | (empty) | Build and run only the named service and its dependencies (multi-service projects) |
--skip-cloud-registration | bool | false | Deploy without registering apps in Cloud (offline use) |
--stagefile-backend | string | (empty) | Stagefile compiler backend: dockerfile (default) or llb |
--user-args | stringSlice | [] | Extra arguments to pass to the container |
--verbose | bool | false | Watch mode (--watch): always show build output (default: hidden unless the build fails) |
--watch | bool | false | Watch the project directory and redeploy on every change, streaming logs between deploys (same as 'wendy watch') |
--yes / -y | bool | false | Automatically accept all interactive prompts |
Output
An attached run streams build progress and app logs. When readiness succeeds and a URL can be inferred, it prints a line such as:
App reachable at http://127.0.0.1:3000The address depends on the target. --detach skips log streaming, host readiness checks, and browser opening. Ordinary single-device agent deployments report configured HTTP endpoints. With --json --detach, one result goes to stdout and progress goes to stderr; readiness: "not_checked" leaves application health unverified. See Details for the result shape and supported modes.
JSON output
The global --json option requests machine-readable output. The CLI also selects JSON mode when no interactive terminal is attached. Support and payloads are command-specific; this flag does not guarantee a single JSON document for commands that stream logs or invoke build tools. Consult Details before parsing command output.
Exit codes
The CLI entry point returns 0 on success and for its user-cancelled or default-cleared results. Other returned errors exit with 1 and print a diagnostic to stderr. Some operations may terminate through subprocess or signal handling; do not infer application health from the CLI exit code alone.
Common errors
Check argument values and flag combinations against the synopsis above. For discovery, build, port, and readiness failures, see deployment troubleshooting. Command-specific constraints are in Details.
See also
Details
Reads wendy.json from the current directory or --prefix directory, builds a container image, and deploys it to the target device.