# uip maestro bpmn init

> Syntax and options for `uip maestro bpmn init`, which scaffolds a new Maestro project with a valid BPMN 2.0 starter and Orchestrator metadata files.

`uip maestro bpmn init` scaffolds a new Maestro project directory with a valid BPMN 2.0 starter and the metadata files Orchestrator expects for process-orchestration packages. It's registered under the `bpmn` branch.

## Synopsis

```
uip maestro bpmn init <name> [--process-id <id>] [--force] [--skip-solution-registration]
```

Honors [global options](./global-options.md). Exit codes follow the [standard contract](./exit-codes.md).

## Arguments

- `<name>` *(required)* — project folder name. Validated against `VALID_PROJECT_NAME_REGEX`: letters, numbers, underscores (`_`), and hyphens (`-`) only.

## Options

| Option | Description |
|---|---|
| `--process-id <id>` | BPMN process ID to write into the generated template. Default: `Process_1`. |
| `--force` | Initialize even if the target directory exists and is non-empty. Existing files are **not** cleared — files are written alongside; this is useful for reinitializing inside a pre-created folder. |
| `--skip-solution-registration` | Do not auto-register this project in the surrounding solution (see Behavior below). |

## Behavior

Creates `<name>/` in the current working directory and writes six files:

| File | Purpose |
|---|---|
| `project.uiproj` | `{ "Name": "<name>", "ProjectType": "ProcessOrchestration" }` |
| `operate.json` | Runtime metadata — `targetFramework: "Portable"`, `contentType: "processOrchestration"`, `runtimeOptions.isAttended: false`. |
| `entry-points.json` | One entry point pointing at `Event_start` inside the starter BPMN, with empty input/output schemas. |
| `bindings_v2.json` | `{ "version": "2.0", "resources": [] }`. |
| `package-descriptor.json` | File manifest consumed by the packer. |
| `<name>.bpmn` | Starter BPMN containing `Event_start` → `_Implicit_EndEvent`, wired with a `uipath:entryPointId` extension using `--process-id` (default `Process_1`). |

The starter BPMN is parsed through `bpmn-moddle` before writing; if structural (non-UiPath-extension) warnings appear, the command fails with `BPMN validation failed: …`.

If `<name>` already exists and is non-empty and `--force` is not set, the command fails with an error.

**Solution auto-registration**: unless `--skip-solution-registration` is passed, `init` looks for a surrounding solution. If run inside one, the new project is registered into it. If run outside any solution, a parent `<name>Solution` is scaffolded automatically and the project is nested inside it — this happens by default, not only when explicitly requested.

## Examples

```bash
# Create a new project in ./invoice-orchestration
uip maestro bpmn init invoice-orchestration

# Set a custom BPMN process ID
uip maestro bpmn init invoice-orchestration --process-id InvoiceApproval

# Reinitialize into an existing non-empty folder
uip maestro bpmn init invoice-orchestration --force

# Scaffold standalone, without touching any surrounding solution
uip maestro bpmn init invoice-orchestration --skip-solution-registration
```

## Data shape (--output json)

```json
{
  "Code": "MaestroInit",
  "Data": {
    "Status": "Created successfully",
    "Path": "/workspace/invoice-orchestration",
    "SolutionRegistration": { "...": "registration outcome against the surrounding or newly created solution" },
    "AutoCreatedSolution": { "...": "present only when a parent <name>Solution was scaffolded automatically" },
    "ProjectArtifacts": { "...": "present only when additional project artifacts were generated" },
    "NextSteps": "present only when SolutionRegistration carries follow-up instructions"
  }
}
```

`AutoCreatedSolution`, `ProjectArtifacts`, and `NextSteps` are omitted entirely when not applicable — only `Status`, `Path`, and `SolutionRegistration` are always present. On failure the response carries `Result: "Failure"`, `Message`, and `Instructions`.

## See also

- [`uip maestro bpmn pack`](./uip-maestro-bpmn-pack.md) — pack the scaffolded project
- [`uip maestro bpmn debug`](./uip-maestro-bpmn-debug.md) — run it via Studio Web
- [`uip maestro bpmn validate`](./uip-maestro-bpmn-validate.md) — validate before packing
- [Maestro overview](./uip-maestro-bpmn.md)