---
title: "wendy install"
description: "Install WendyOS or Wendy Lite firmware on a device"
---

## Syntax

```sh
wendy install [image] [drive] [flags]
```

## Examples

```sh
wendy install --help
```

## Arguments

Argument notation from the CLI: `[image] [drive]`. Angle brackets mark required values; square brackets mark optional values. See Details for command-specific validation.

## 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 |
| --- | --- | --- | --- |
| `--cloud-grpc` | string | (empty) | Cloud gRPC endpoint of the auth session to use for pre-enrollment (optional when a default is set via 'wendy auth use') |
| `--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 |
| `--device-name` | string | (empty) | Set device name on first boot (e.g. brave-dolphin) |
| `--device-type` | string | (empty) | Device type from manifest (e.g. raspberry-pi-5) |
| `--drive` | string | (empty) | Target drive path (e.g. /dev/disk4) |
| `--force` | bool | `false` | Skip confirmation prompt |
| `--json` | bool | `false` | Output in JSON format |
| `--nightly` | bool | `false` | Use nightly/prerelease builds |
| `--no-bmap` | bool | `false` | Disable bmap-accelerated flashing even when a block map is available |
| `--no-wifi` | bool | `false` | Skip WiFi setup entirely (no interactive prompt, no pre-seeded networks) |
| `--pr` | int | `0` | Install the image built by wendyos-builder PR #N (debug build; mutually exclusive with --nightly, --version, and positional [image] [drive]) |
| `--pre-enroll` | bool | `false` | Pre-enroll this device with Wendy Cloud during imaging (requires 'wendy auth login') |
| `--rootfs-only` | bool | `false` | Write only the SD/NVMe rootfs image; does not update Jetson QSPI boot firmware |
| `--storage` | string | (empty) | Force image storage variant: nvme or sd (default: auto-detect — real NVMe drives use nvme; a USB-attached drive uses the device's published image, SD for Raspberry Pi / NVMe for Jetson SSD enclosures). For jetson-agx-orin, emmc flashes the onboard eMMC over USB recovery instead of writing a drive |
| `--version` | string | (empty) | WendyOS version to install (interactive if omitted) |
| `--wifi` | stringArray | `[]` | Pre-configure a WiFi network. Repeatable. Format: ssid=X[,password=Y][,priority=N][,hidden=true][,security=wpa2] |
| `--wifi-password` | string | (empty) | Password for --wifi-ssid |
| `--wifi-ssid` | string | (empty) | Pre-configure a single WiFi SSID on first boot (shortcut for --wifi) |
| `--yes-overwrite-internal` | bool | `false` | Required to wipe an internal (non-removable) drive in non-interactive mode |

## Output

Output depends on the operation and selected target. [Command behavior and detailed examples](../../../advanced/clients/wendy-cli/commands/install/).

## 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](../../../errors/). Command-specific constraints are in Details.

## See also

- [wendy](../../../reference/cli/)
- [wendy install jobs](../../../reference/cli/install/jobs/)
- [wendy install plan](../../../reference/cli/install/plan/)
- [wendy install verify](../../../reference/cli/install/verify/)
- [CLI conventions and configuration](../../../reference/)

## Details

Interactively select a supported device, download the latest OS image or firmware, and write it to the target.

When called with positional arguments, skips interactive prompts:
  wendy os install <image-path> <drive-id> --force

When called with manifest-backed flags, installs a specific version:
  wendy os install --device-type raspberry-pi-5 --version 0.10.4 --drive /dev/disk4 --force

Pre-seed multiple WiFi networks (repeatable, highest-priority first):
  wendy os install --device-type raspberry-pi-5 --drive /dev/disk4 --force \
    --wifi "ssid=Home,password=hunter2,priority=100" \
    --wifi "ssid=Office,password=corp,priority=50" \
    --wifi "ssid=Cafe,hidden=true"

Flags can be provided progressively — omitted values trigger interactive pickers.

[Command behavior and detailed examples](../../../advanced/clients/wendy-cli/commands/install/)