# Formations Commands

> See [Formations module docs](../../modules/formations) for permissions and data model.

# Formations Commands

See [Formations module docs](../../modules/formations) for permissions and data model.

### `soat validate-formation`

Validate a formation template

- Method: `POST`
- Path: `/api/v1/formations/validate`

#### Usage

```bash
soat validate-formation
```

#### Options

##### `--template`

A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing. 

- Source: `body`
- Required: no
- Type: `object \| string`

##### `--parameters`

Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. When provided, the validation result also reports required parameters that are still missing after applying these values. 

- Source: `body`
- Required: no
- Type: `object<string, string>`

##### `--template-path`

Read template from a local JSON/YAML file and map it to body.template.

- Source: `wrapper`
- Required: no
- Type: `string`
- Notes: Mutually exclusive with --template and --template-file.

##### `--template-file`

Alias of --template-path.

- Source: `wrapper`
- Required: no
- Type: `string`
- Notes: Mutually exclusive with --template and --template-path.

### `soat plan-formation`

Plan a formation deployment

- Method: `POST`
- Path: `/api/v1/formations/plan`

#### Usage

```bash
soat plan-formation --template <object | string>
```

#### Options

##### `--project-id`

Project ID. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise.

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--formation-id`

Existing formation ID to compare against. Omit for new formation planning.

- Source: `body`
- Required: no
- Type: `string`

##### `--template`

A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing. 

- Source: `body`
- Required: yes
- Type: `object \| string`

##### `--parameters`

Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. A parameter declared with `use_previous_value: true` may be omitted to reuse its stored value. 

- Source: `body`
- Required: no
- Type: `object<string, string>`

##### `--template-path`

Read template from a local JSON/YAML file and map it to body.template.

- Source: `wrapper`
- Required: no
- Type: `string`
- Notes: Mutually exclusive with --template and --template-file.

##### `--template-file`

Alias of --template-path.

- Source: `wrapper`
- Required: no
- Type: `string`
- Notes: Mutually exclusive with --template and --template-path.

##### `--parameter`

Repeatable parameter assignment merged into body.parameters. Values support $VAR, $\{VAR\}, or @VAR_NAME (shell-safe env-file reference). Omit the value (--parameter KEY) to auto-read KEY from the merged env.

- Source: `wrapper`
- Required: no
- Type: `string (repeatable key=value or key)`
- Notes: Mutually exclusive with --parameters.

##### `--env-file`

Load environment variables from file for resolving $VAR, $\{VAR\}, and @VAR_NAME in --parameter values.

- Source: `wrapper`
- Required: no
- Type: `string`

### `soat list-formations`

List formations

- Method: `GET`
- Path: `/api/v1/formations`

#### Usage

```bash
soat list-formations
```

#### Options

##### `--project-id`

Project ID (required if not using project key auth)

- Source: `query`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--limit`

Maximum number of results to return

- Source: `query`
- Required: no
- Type: `integer`
- Default: `50`

##### `--offset`

Number of results to skip

- Source: `query`
- Required: no
- Type: `integer`
- Default: `0`

### `soat create-formation`

Create a new formation

- Method: `POST`
- Path: `/api/v1/formations`

#### Usage

```bash
soat create-formation --name <string> --template <object | string>
```

#### Options

##### `--project-id`

Project ID. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise.

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--name`

Human-readable name for the formation stack

- Source: `body`
- Required: yes
- Type: `string`
- Example: `my-agent-stack`

##### `--template`

A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing. 

- Source: `body`
- Required: yes
- Type: `object \| string`

##### `--parameters`

Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. Required parameters (those without a default) must be provided here. 

- Source: `body`
- Required: no
- Type: `object<string, string>`

##### `--metadata`

Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`. 

- Source: `body`
- Required: no
- Type: `object<string, unknown>`

##### `--template-path`

Read template from a local JSON/YAML file and map it to body.template.

- Source: `wrapper`
- Required: no
- Type: `string`
- Notes: Mutually exclusive with --template and --template-file.

##### `--template-file`

Alias of --template-path.

- Source: `wrapper`
- Required: no
- Type: `string`
- Notes: Mutually exclusive with --template and --template-path.

##### `--parameter`

Repeatable parameter assignment merged into body.parameters. Values support $VAR, $\{VAR\}, or @VAR_NAME (shell-safe env-file reference). Omit the value (--parameter KEY) to auto-read KEY from the merged env.

- Source: `wrapper`
- Required: no
- Type: `string (repeatable key=value or key)`
- Notes: Mutually exclusive with --parameters.

##### `--env-file`

Load environment variables from file for resolving $VAR, $\{VAR\}, and @VAR_NAME in --parameter values.

- Source: `wrapper`
- Required: no
- Type: `string`

### `soat get-formation`

Get a specific formation

- Method: `GET`
- Path: `/api/v1/formations/{formation_id}`

#### Usage

```bash
soat get-formation --formation-id <string>
```

#### Options

##### `--formation-id`

—

- Source: `path`
- Required: yes
- Type: `string`
- Example: `form_V1StGXR8Z5jdHi6B`

### `soat update-formation`

Update an formation

- Method: `PUT`
- Path: `/api/v1/formations/{formation_id}`

#### Usage

```bash
soat update-formation --formation-id <string>
```

#### Options

##### `--formation-id`

—

- Source: `path`
- Required: yes
- Type: `string`
- Example: `form_V1StGXR8Z5jdHi6B`

##### `--template`

A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing. 

- Source: `body`
- Required: no
- Type: `object \| string`

##### `--parameters`

Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. Required parameters (those without a default) must be provided here, unless the parameter is declared with `use_previous_value: true`, in which case omitting it reuses the previously stored value. 

- Source: `body`
- Required: no
- Type: `object<string, string>`

##### `--metadata`

Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`. 

- Source: `body`
- Required: no
- Type: `object<string, unknown>`

##### `--template-path`

Read template from a local JSON/YAML file and map it to body.template.

- Source: `wrapper`
- Required: no
- Type: `string`
- Notes: Mutually exclusive with --template and --template-file.

##### `--template-file`

Alias of --template-path.

- Source: `wrapper`
- Required: no
- Type: `string`
- Notes: Mutually exclusive with --template and --template-path.

##### `--parameter`

Repeatable parameter assignment merged into body.parameters. Values support $VAR, $\{VAR\}, or @VAR_NAME (shell-safe env-file reference). Omit the value (--parameter KEY) to auto-read KEY from the merged env.

- Source: `wrapper`
- Required: no
- Type: `string (repeatable key=value or key)`
- Notes: Mutually exclusive with --parameters.

##### `--env-file`

Load environment variables from file for resolving $VAR, $\{VAR\}, and @VAR_NAME in --parameter values.

- Source: `wrapper`
- Required: no
- Type: `string`

### `soat delete-formation`

Delete an formation

- Method: `DELETE`
- Path: `/api/v1/formations/{formation_id}`

#### Usage

```bash
soat delete-formation --formation-id <string>
```

#### Options

##### `--formation-id`

—

- Source: `path`
- Required: yes
- Type: `string`
- Example: `form_V1StGXR8Z5jdHi6B`

### `soat list-formation-events`

List formation operation events

- Method: `GET`
- Path: `/api/v1/formations/{formation_id}/events`

#### Usage

```bash
soat list-formation-events --formation-id <string>
```

#### Options

##### `--formation-id`

—

- Source: `path`
- Required: yes
- Type: `string`
- Example: `form_V1StGXR8Z5jdHi6B`

##### `--limit`

Maximum number of results to return

- Source: `query`
- Required: no
- Type: `integer`
- Default: `50`

##### `--offset`

Number of results to skip

- Source: `query`
- Required: no
- Type: `integer`
- Default: `0`