Global Flags

These flags are available on every wendy command.

--json

Outputs command results as JSON instead of the default interactive TUI or table format.

wendy device list --json

For ordinary single-device deployments to a Wendy agent, wendy --json run --detach emits one result on stdout, with progress and pre-start logs on stderr. See wendy run — Detached output for the result shape and supported modes. Attached run and build commands still emit progress/log output.

When stdout is not a TTY (for example, when piping output, running in CI, or executing from a script), --json is automatically enabled. An explicit --json or --json=false always takes precedence over the automatic detection.

# JSON output without passing --json explicitly
wendy device list | cat

# Suppress JSON even in a non-TTY context
wendy device list --json=false | cat

In JSON mode stdout carries only JSON. Notices that change what a result means are written to stderr as single plain lines instead of being dropped: the device a command picked for you (Using default device wendyos-abc.local.) and certificate warnings. Onboarding hints such as "Next: run wendy run …" are not shown in JSON mode.

Note: For live, full-screen TUI commands such as wendy device top, --json does not stream the interface — it switches the command to a one-shot snapshot mode that prints a single JSON object and exits, instead of rendering the interactive dashboard.

Errors in JSON mode

When a command fails in JSON mode, it writes nothing more to stdout, and the last line on stderr is one JSON object:

{"error":{"code":"device_unreachable","exit":5,"message":"Could not connect to device at 192.168.1.42:50051. Is it powered on and connected to the network?","retryable":true,"next_steps":[]}}

Earlier stderr lines can hold progress output and notices, so read the last line. Outside JSON mode the same failure prints as styled text. So does a failure in automatic JSON mode when stderr is a terminal, as in wendy device apps list | grep my-app: stdout is piped, but the error is read by a person. Pass --json explicitly to get the JSON error there too.

Exit status

wendy exits with the same status whether or not JSON mode is on.

device_not_resolved means DNS reported that the host name does not exist. That can also happen while this machine is offline, so check the network before the name. A device name resolved over mDNS (a .local name, or a bare name such as wendyos-abc) that does not resolve is device_unreachable instead, since it resolves only while the device is on the network.

retryable is true for device_unreachable, device_offline, transfer_failed, registry_unavailable, readiness_timeout, and the timeouts grpc_deadline and network_timeout.

--device

Specifies a target device by IP address, hostname, provider key, or explicit host:port, bypassing device selection.

wendy --device 192.168.1.42 device apps list
wendy --device my-mac.local:50051 device info --json

When --device is not given, the CLI uses the WENDY_DEVICE environment variable if it is set, and only then the saved default device. Set WENDY_DEVICE per terminal, or in an AI tool's MCP server env block, to give each session its own target without changing the default all sessions share:

export WENDY_DEVICE=my-pi.local
wendy device info                             # my-pi.local
wendy --device my-mac.local:50051 device info # --device still wins

Commands that connect to a device this way print Using device <name> from WENDY_DEVICE. The notice is not printed in --json mode, which the CLI also switches to on its own when it runs without an interactive terminal: from an AI tool's MCP server, a script, or a pipe.

Automatic update notifications

Ordinary commands check for a newer release in the background. A successful check is cached for 24 hours; a failed or cancelled check can retry after one hour.

In an interactive terminal, the CLI prompts Update now? with Yes selected. Declining snoozes that release's prompt for 24 hours. Non-interactive and --json invocations print notices to stderr without prompting.

Accepted updates use the installation's owning package manager. For Homebrew stable, the commands are brew update and brew upgrade wendylabsinc/tap/wendy. See wendy update for supported methods, manual instructions, and verification after an update.

CI, read-only checks, and completion helpers skip background reminders. Set WENDY_NO_UPDATE_CHECK=1 to disable them for other commands. Explicit wendy update and wendy update --check still work.

Automatic shell-completion prompt

When shell completions aren't installed, the CLI offers — at most once per 24-hour window — to install them with an ambient Install them now? [y/n] prompt after a command finishes. It is never shown in non-interactive or --json contexts, on commands that handle completions themselves (wendy completion …, wendy tour), or once completions are installed or the prompt is dismissed. See wendy completion for the full behavior.

Its state is persisted in ~/.wendy/config.json:

Environment variables