# uip maestro bpmn format

> Syntax and options for `uip maestro bpmn format`, which generates or replaces the BPMNDiagram layout section of a .bpmn file.

`uip maestro bpmn format` generates or replaces the `bpmndi:BPMNDiagram` layout section in a `.bpmn` file, using a left-to-right breadth-first layout. Useful after hand-editing or generating a `.bpmn` file's logical content without also producing valid diagram coordinates. It's registered under the `bpmn` branch.

## Synopsis

```
uip maestro bpmn format <bpmn> [--output-file <file>]
```

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

## Arguments

- `<bpmn>` *(required)* — path to the `.bpmn` file.

## Options

| Option | Default | Description |
|---|---|---|
| `--output-file <file>` | overwrites `<bpmn>` | Write the formatted output to a different file instead of overwriting the input. |

## Examples

```bash
# Overwrite the file's own layout
uip maestro bpmn format process.bpmn

# Write formatted output elsewhere, keeping the original untouched
uip maestro bpmn format process.bpmn --output-file process.formatted.bpmn
```

## Data shape (--output json)

```json
{
  "Code": "MaestroBpmnFormat",
  "Data": {
    "File": "/path/to/process.bpmn",
    "ShapeCount": 5,
    "EdgeCount": 4
  }
}
```

## See also

- [`uip maestro bpmn validate`](./uip-maestro-bpmn-validate.md) — structurally validate a `.bpmn` file
- [`uip maestro bpmn refresh`](./uip-maestro-bpmn-refresh.md) — regenerate project metadata from a `.bpmn`
- [Maestro overview](./uip-maestro-bpmn.md)