Skip to main content

Formations Commands

See Formations module docs for permissions and data model.

soat validate-formation​

Validate a formation template

  • Method: POST
  • Path: /api/v1/formations/validate

Usage​

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​

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​

soat list-formations

Options​

--project-id​

Project ID (required if not using project key auth)

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B

soat create-formation​

Create a new formation

  • Method: POST
  • Path: /api/v1/formations

Usage​

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: 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​

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​

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: 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​

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​

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

Options​

--formation-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: form_V1StGXR8Z5jdHi6B