---
title: "wendy init"
description: "Initialize a new Wendy project"
---

## Syntax

```sh
wendy init [app-id] [flags]
```

## Examples

```sh
wendy init
wendy init hello-wendy --target wendyos --language node --template simple-api --var PORT=3000 --assistant skip --git-init no
```

## Arguments

Argument notation from the CLI: `[app-id]`. 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 |
| --- | --- | --- | --- |
| `--all-entitlements` | bool | `false` | Enable all entitlements (requires field flags for gpio, i2c, persist) |
| `--app-id` | string | (empty) | Application ID to write into wendy.json |
| `--assistant` | string | (empty) | AI assistant to launch after init: claude, codex, or skip |
| `--branch` | string | (empty) | Branch of the templates repo to use (default: main) |
| `--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 |
| `--entitlement` | stringSlice | `[]` | App entitlement to enable (repeatable or comma-separated) |
| `--framework` | stringSlice | `[]` | App framework to enable in wendy.json's top-level "frameworks" key (repeatable or comma-separated; currently: ros2) |
| `--git-init` | string | (empty) | Initialize a git repo in the project directory (yes or no) |
| `--gpio-pins` | string | (empty) | GPIO pins for the gpio entitlement (comma-separated, e.g. 17,27,22) |
| `--here` | bool | `false` | Scaffold into the current directory instead of creating a subdirectory |
| `--i2c-device` | string | (empty) | I2C device path for the i2c entitlement (e.g. /dev/i2c-1) |
| `--install-claude-skills` | bool | `false` | Install Wendy Claude skills before launching Claude |
| `--json` | bool | `false` | Output in JSON format |
| `--language` | string | (empty) | Project language: python, swift, rust, node, cpp, or mojo |
| `--no-extra-entitlements` | bool | `false` | Skip entitlement prompts and use only the default network entitlement |
| `--persist-name` | string | (empty) | Container ID for the persist entitlement |
| `--persist-path` | string | (empty) | Mount path for the persist entitlement (e.g. /data) |
| `--ros2-discovery-scope` | string | (empty) | ROS 2 discovery scope: app (default, isolated) or host (shared with the device's host network) |
| `--ros2-distro` | string | (empty) | ROS 2 distribution (default: humble) |
| `--ros2-domain-id` | int | `-1` | ROS 2 domain ID, 0-232 (default: derived from the app ID) |
| `--ros2-rmw` | string | (empty) | ROS 2 middleware implementation: cyclonedds (default), fastrtps, connextdds, or gurumdds |
| `--target` | string | (empty) | Target platform: wendyos (writes "linux" to wendy.json), wendy-lite, or darwin |
| `--template` | string | (empty) | Project template (e.g. simple-api, fullstack) |
| `--var` | stringSlice | `[]` | Template variable override (repeatable, KEY=VALUE) |

## Output

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

## 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/)
- [CLI conventions and configuration](../../../reference/)

## Details

Interactively create a new Wendy project with scaffolding, entitlements, and optional AI assistant setup.

An [app-id] argument (or --app-id) creates a new subdirectory of that name by default; pass --here to scaffold into the current directory instead (with no app ID, --here infers one from the current directory's name).

wendy.json also supports a separate, top-level "frameworks" key for framework-level config (currently ROS 2: domain ID, RMW middleware, discovery scope). Enable it with --framework (see the ROS 2 example below), through the interactive prompt on a WendyOS target, or by hand-editing "frameworks" in wendy.json afterwards.

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