### Agent Management

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Start and stop the Formae agent. The agent can be started with default or custom configuration.

```APIDOC
## CLI Commands for Agent Management

### Description
Commands to manage the Formae agent, including starting and stopping it.

### Method
CLI Command

### Endpoint
N/A (CLI commands)

### Parameters
#### `formae agent start`
- **--config** (string) - Optional - Path to a custom configuration file (e.g., PKL format).

#### `formae agent stop`
- No parameters.

### Request Example
```bash
# Start the agent with default configuration
formae agent start

# Start the agent with custom config
formae agent start --config /path/to/config.pkl

# Stop the agent
formae agent stop
```

### Response
N/A (CLI output)

### Response Example
(Output will vary based on agent status and configuration)
```
Formae agent started successfully.
```
```

--------------------------------

### Control Formae Agent

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Commands to start and stop the Formae background agent. Allows for custom configuration file paths during startup.

```bash
formae agent start
formae agent start --config /path/to/config.pkl
formae agent stop
```

--------------------------------

### Get Agent Statistics using CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve usage statistics from the Formae agent, including resource counts, resource types, and plugin information.

```bash
curl -X GET "http://localhost:49684/api/v1/stats"
```

--------------------------------

### Get Agent Statistics API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve usage statistics from the Formae agent.

```APIDOC
## GET /api/v1/stats

### Description
Retrieve usage statistics from the Formae agent.

### Method
GET

### Endpoint
/api/v1/stats

### Response
#### Success Response (200)
- **Stats Object**: Contains 'AgentId', 'Version', 'Resources', 'ResourceTypes', 'Stacks', and 'Plugins'.

#### Response Example
```json
{
  "AgentId": "agent-001",
  "Version": "0.15.0",
  "Resources": {"AWS": 42, "GCP": 15},
  "ResourceTypes": {"AWS::S3::Bucket": 10, "AWS::EC2::Instance": 5},
  "Stacks": 8,
  "Plugins": [
    {
      "Namespace": "AWS",
      "NodeName": "formae-aws-plugin",
      "Version": "0.3.0",
      "ResourceCount": 42
    }
  ]
}
```
```

--------------------------------

### Get Stack Drift API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve resource modifications (drift) since the last reconcile for a specific stack.

```APIDOC
## GET /api/v1/stacks/{stack_label}/drift

### Description
Retrieve resource modifications (drift) since the last reconcile.

### Method
GET

### Endpoint
/api/v1/stacks/{stack_label}/drift

#### Path Parameters
- **stack_label** (string) - Required - The label of the stack to get drift information for.

### Response
#### Success Response (200)
- **Drift Object**: Contains a list of 'ModifiedResources', each with 'Label', 'Type', 'Stack', and 'Operation'.

#### Response Example
```json
{
  "ModifiedResources": [
    {
      "Label": "my-bucket",
      "Type": "AWS::S3::Bucket",
      "Stack": "my-stack",
      "Operation": "Update"
    }
  ]
}
```
```

--------------------------------

### Get Command Status

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve the status of previously submitted commands. Can fetch status for a specific command, multiple commands via query, or the most recent command.

```APIDOC
## GET /api/v1/commands/{command_id}/status and GET /api/v1/commands/status

### Description
Retrieve the status of a previously submitted command or multiple commands.

### Method
GET

### Endpoint
- `/api/v1/commands/{command_id}/status`: Get status for a specific command.
- `/api/v1/commands/status`: Get status for multiple commands based on query parameters or the most recent command.

### Parameters
#### Path Parameters
- **command_id** (string) - Required - The ID of the command to retrieve status for (used with the first endpoint).

#### Query Parameters (for `/api/v1/commands/status`)
- **query** (string) - Optional - A query to filter commands by status (e.g., 'state:inprogress').
- **max_results** (integer) - Optional - The maximum number of command statuses to return.

### Request Example
```bash
# Get status of a specific command
curl -X GET "http://localhost:49684/api/v1/commands/2NxgVh8WqTmJK9CvYpRsZD3EaFb/status" \
  -H "Client-ID: my-client-001"

# Query multiple commands status
curl -X GET "http://localhost:49684/api/v1/commands/status?query=state:inprogress&max_results=10" \
  -H "Client-ID: my-client-001"

# Get most recent command status
curl -X GET "http://localhost:49684/api/v1/commands/status" \
  -H "Client-ID: my-client-001"
```

### Response
#### Success Response (200 OK)
- **Commands** (array) - A list of command status objects.
  - **CommandId** (string) - The ID of the command.
  - **Command** (string) - The type of command (e.g., 'apply').
  - **State** (string) - The current state of the command (e.g., 'Success', 'Failed', 'Pending').
  - **StartTs** (string) - The timestamp when the command started.
  - **EndTs** (string) - The timestamp when the command ended.
  - **ResourceUpdates** (array) - A list of resource updates performed by the command.
    - **ResourceLabel** (string) - The label of the resource.
    - **ResourceType** (string) - The type of the resource.
    - **Operation** (string) - The operation performed on the resource (e.g., 'Create').
    - **State** (string) - The state of the resource update (e.g., 'Success').

#### Response Example
```json
{
  "Commands": [{
    "CommandId": "2NxgVh8WqTmJK9CvYpRsZD3EaFb",
    "Command": "apply",
    "State": "Success",
    "StartTs": "2025-01-15T10:30:00Z",
    "EndTs": "2025-01-15T10:31:45Z",
    "ResourceUpdates": [{
      "ResourceLabel": "my-bucket",
      "ResourceType": "AWS::S3::Bucket",
      "Operation": "Create",
      "State": "Success"
    }]
  }]
}
```
```

--------------------------------

### Get Stack Drift using CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Check for resource modifications (drift) within a specific stack since its last reconciliation. This helps identify unintended changes.

```bash
curl -X GET "http://localhost:49684/api/v1/stacks/my-stack/drift"
```

--------------------------------

### Initialize Formae Plugins

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Scaffolds new Formae plugins using templates. Supports both interactive prompts and non-interactive flag-based configuration.

```bash
formae plugin init
formae plugin init \
  --name my-plugin \
  --namespace MYCLOUD \
  --description "My custom cloud provider plugin" \
  --author "My Organization" \
  --module-path github.com/my-org/formae-plugin-mycloud \
  --license Apache-2.0 \
  --output-dir ./formae-plugin-mycloud \
  --no-input
```

--------------------------------

### List Policies using CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve standalone policies and their associated stacks. Policies define rules or configurations for resources.

```bash
curl -X GET "http://localhost:49684/api/v1/policies"
```

--------------------------------

### Plugin Management

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Initialize new Formae plugins from a template. Supports interactive and non-interactive modes.

```APIDOC
## CLI Commands for Plugin Management

### Description
Commands to initialize new Formae plugins from a template.

### Method
CLI Command

### Endpoint
N/A (CLI commands)

### Parameters
#### `formae plugin init`
- **--name** (string) - Optional - The name of the plugin.
- **--namespace** (string) - Optional - The namespace for the plugin.
- **--description** (string) - Optional - A description for the plugin.
- **--author** (string) - Optional - The author of the plugin.
- **--module-path** (string) - Optional - The module path for the plugin (e.g., 'github.com/my-org/formae-plugin-mycloud').
- **--license** (string) - Optional - The license for the plugin (e.g., 'Apache-2.0').
- **--output-dir** (string) - Optional - The directory where the plugin will be created.
- **--no-input** (boolean) - Optional - If set, runs in non-interactive mode, using provided arguments or defaults.

### Request Example
```bash
# Interactive plugin initialization
formae plugin init

# Non-interactive plugin initialization
formae plugin init \
  --name my-plugin \
  --namespace MYCLOUD \
  --description "My custom cloud provider plugin" \
  --author "My Organization" \
  --module-path github.com/my-org/formae-plugin-mycloud \
  --license Apache-2.0 \
  --output-dir ./formae-plugin-mycloud \
  --no-input
```

### Response
N/A (CLI output)

### Response Example
(Output will indicate successful plugin initialization and the location of the created plugin files)
```
Plugin 'my-plugin' initialized successfully in './formae-plugin-mycloud'.
```
```

--------------------------------

### Evaluate Infrastructure with Formae CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Evaluates a Pkl infrastructure file and outputs the result in a specified format. Useful for generating machine-readable configuration schemas.

```bash
formae eval my-infrastructure.pkl --output-consumer machine --output-schema json
```

--------------------------------

### Force Discovery using CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Initiate an immediate discovery process to find new or updated resources in the configured cloud targets. This is useful after making changes in the cloud environment.

```bash
curl -X POST "http://localhost:49684/api/v1/admin/discover"
```

--------------------------------

### List Cloud Targets using CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve a list of configured cloud targets (accounts/regions) from the Formae agent. Supports filtering targets by query parameters like namespace and discoverability.

```bash
# List all targets
curl -X GET "http://localhost:49684/api/v1/targets"

# Filter targets by query
curl -X GET "http://localhost:49684/api/v1/targets?query=namespace:AWS%20discoverable:true"
```

--------------------------------

### List Stacks using CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve all stacks managed by the Formae agent. A stack represents a collection of cloud resources.

```bash
curl -X GET "http://localhost:49684/api/v1/stacks"
```

--------------------------------

### Agent Configuration using Pkl

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Configure the Formae agent's operational settings, including server details, datastore connection, retry mechanisms, discovery and synchronization intervals, logging, and OpenTelemetry integration.

```pkl
amends "package://pkg.pkl-lang.org/github.com/platform-engineering-labs/formae/formae@0.15.0#/Config.pkl"

agent {
    server {
        nodename = "formae"
        hostname = "localhost"
        port = 49684
        tlsCert = "/path/to/cert.pem"
        tlsKey = "/path/to/key.pem"
    }

    datastore {
        datastoreType = "postgres"
        postgres {
            host = "localhost"
            port = 5432
            user = "formae"
            password = "secret"
            database = "formae"
        }
    }

    retry {
        maxRetries = 9
        retryDelay = 10.s
        statusCheckInterval = 20.s
    }

    discovery {
        enabled = true
        interval = 10.min
        labelTagKeys {
            "Name"
            "Environment"
        }
    }

    synchronization {
        enabled = true
        interval = 5.min
    }

    logging {
        filePath = "~/.pel/formae/log/formae.log"
        fileLogLevel = "debug"
        consoleLogLevel = "info"
    }

    oTel {
        enabled = true
        serviceName = "formae-agent"
        otlp {
            endpoint = "http://localhost:4317"
            protocol = "grpc"
        }
        prometheus {
            enabled = true
        }
    }
}

plugins {
    pluginDir = "~/.pel/formae/plugins"
}
```

--------------------------------

### Submit Apply Command

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Submit an apply command to create or update infrastructure resources. Supports reconcile and patch modes, with options for simulation and forcing reconciliation.

```APIDOC
## POST /api/v1/commands

### Description
Submit an apply command to create or update infrastructure resources.

### Method
POST

### Endpoint
/api/v1/commands

### Parameters
#### Query Parameters
- **command** (string) - Required - The command to execute, e.g., 'apply'.
- **mode** (string) - Optional - The mode of the apply command ('reconcile' or 'patch'). Defaults to 'reconcile'.
- **simulate** (boolean) - Optional - If true, simulates the command without making changes. Defaults to false.
- **force** (boolean) - Optional - If true, forces reconciliation and overwrites external changes. Defaults to false.

#### Request Body
- **file** (file) - Required - The Formae configuration file (e.g., JSON) to apply.

### Request Example
```bash
curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=apply" \
  -F "mode=reconcile" \
  -F "simulate=false" \
  -F "file=@forma.json"
```

### Response
#### Success Response (202 Accepted)
- **CommandId** (string) - The ID of the submitted command.
- **Simulation** (object) - Details of the simulation if `simulate` was true.
  - **ChangesRequired** (boolean) - Indicates if changes are required.
  - **Command** (object) - The simulated command details.
    - **CommandId** (string) - The ID of the simulated command.
    - **Command** (string) - The type of command (e.g., 'apply').
    - **State** (string) - The initial state of the command (e.g., 'Pending').
    - **ResourceUpdates** (array) - A list of simulated resource updates.

#### Response Example
```json
{
  "CommandId": "2NxgVh8WqTmJK9CvYpRsZD3EaFb",
  "Simulation": {
    "ChangesRequired": true,
    "Command": {
      "CommandId": "2NxgVh8WqTmJK9CvYpRsZD3EaFb",
      "Command": "apply",
      "State": "Pending",
      "ResourceUpdates": []
    }
  }
}
```
```

--------------------------------

### Target Configuration using Pkl

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Define cloud targets for Formae to manage, specifying details for AWS and GCP accounts, including labels, namespaces, discoverability, and specific configuration parameters like region, project, and profile.

```pkl
amends "package://pkg.pkl-lang.org/github.com/platform-engineering-labs/formae/formae@0.15.0#/Config.pkl"

local awsTarget = new Target {
    label = "aws-production-us-east-1"
    namespace = "AWS"
    discoverable = true
    config {
        type = "aws"
        region = "us-east-1"
        profile = "production"
    }
}

local gcpTarget = new Target {
    label = "gcp-production-us-central1"
    namespace = "GCP"
    discoverable = false
    config {
        type = "gcp"
        project = "my-project"
        region = "us-central1"
    }
}
```

--------------------------------

### CLI Configuration using Pkl

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Configure the Formae CLI's connection settings to interact with the Formae agent API, including the API URL and port. It also allows disabling usage reporting.

```pkl
amends "package://pkg.pkl-lang.org/github.com/platform-engineering-labs/formae/formae@0.15.0#/Config.pkl"

cli {
    api {
        url = "http://localhost"
        port = 49684
    }
    disableUsageReporting = false
}
```

--------------------------------

### Force Discovery API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Trigger immediate discovery of resources.

```APIDOC
## POST /api/v1/admin/discover

### Description
Trigger immediate discovery of resources.

### Method
POST

### Endpoint
/api/v1/admin/discover

### Response
#### Success Response (200)
- Returns 200 OK upon successful discovery trigger.
```

--------------------------------

### Force Synchronization using CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Trigger an immediate synchronization of resource states across all managed targets. This ensures the agent's state reflects the actual cloud environment.

```bash
curl -X POST "http://localhost:49684/api/v1/admin/synchronize"
```

--------------------------------

### Submit Apply Command via REST API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Submits infrastructure apply requests to the Formae API. Supports reconcile and patch modes, as well as simulation flags.

```curl
curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=apply" \
  -F "mode=reconcile" \
  -F "simulate=false" \
  -F "file=@forma.json"

curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=apply" \
  -F "mode=patch" \
  -F "simulate=true" \
  -F "file=@patch.json"

curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=apply" \
  -F "mode=reconcile" \
  -F "force=true" \
  -F "file=@forma.json"
```

--------------------------------

### Configure Git for SSH Commit Signing

Source: https://github.com/platform-engineering-labs/formae/blob/main/CONTRIBUTING.md

Configures the local Git environment to use SSH keys for signing commits. Requires an existing SSH key uploaded to GitHub and sets the signing format to SSH.

```bash
git config gpg.format ssh
git config user.signingkey ~/.ssh/id_ed25519
git config commit.gpgSign true
```

--------------------------------

### Health Check using CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Perform a health check on the Formae API server to verify it is running and responsive.

```bash
curl -X GET "http://localhost:49684/api/v1/health"
```

--------------------------------

### Submit Destroy Command

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Submit a destroy command to delete infrastructure resources. Can target resources by file or query.

```APIDOC
## POST /api/v1/commands

### Description
Submit a destroy command to delete infrastructure resources.

### Method
POST

### Endpoint
/api/v1/commands

### Parameters
#### Query Parameters
- **command** (string) - Required - The command to execute, 'destroy'.
- **simulate** (boolean) - Optional - If true, simulates the command without making changes. Defaults to false.
- **file** (file) - Optional - The Formae configuration file to destroy resources defined in.
- **query** (string) - Optional - A query to select resources for destruction (e.g., 'type:AWS::S3::Bucket stack:my-stack').

### Request Example
```bash
# Destroy by forma file
curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=destroy" \
  -F "simulate=false" \
  -F "file=@forma.json"

# Destroy by query
curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=destroy" \
  -F "query=type:AWS::S3::Bucket stack:my-stack"
```

### Response
#### Success Response (202 Accepted)
- **CommandId** (string) - The ID of the submitted command.
- **Simulation** (object) - Details of the simulation if `simulate` was true.
  - **ChangesRequired** (boolean) - Indicates if changes are required.
  - **Command** (object) - The simulated command details.
    - **CommandId** (string) - The ID of the simulated command.
    - **Command** (string) - The type of command (e.g., 'destroy').
    - **State** (string) - The initial state of the command (e.g., 'Pending').
    - **ResourceUpdates** (array) - A list of simulated resource updates.

#### Response Example
```json
{
  "CommandId": "2NxgVh8WqTmJK9CvYpRsZD3EaFb",
  "Simulation": {
    "ChangesRequired": true,
    "Command": {
      "CommandId": "2NxgVh8WqTmJK9CvYpRsZD3EaFb",
      "Command": "destroy",
      "State": "Pending",
      "ResourceUpdates": []
    }
  }
}
```
```

--------------------------------

### List Resources

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Query resources currently managed by Formae. Resources can be filtered by various criteria using a query string.

```APIDOC
## GET /api/v1/resources

### Description
Query resources in the inventory.

### Method
GET

### Endpoint
/api/v1/resources

### Parameters
#### Query Parameters
- **query** (string) - Required - A query string to filter resources (e.g., 'type:AWS::S3::Bucket', 'stack:production', 'label:my-resource').

### Request Example
```bash
# List all resources matching a query
curl -X GET "http://localhost:49684/api/v1/resources?query=type:AWS::S3::Bucket" \
  -H "Client-ID: my-client-001"

# Query by stack
curl -X GET "http://localhost:49684/api/v1/resources?query=stack:production" \
  -H "Client-ID: my-client-001"
```

### Response
#### Success Response (200 OK)
- **Resources** (array) - A list of resource objects matching the query.
  - **Label** (string) - The label of the resource.
  - **Type** (string) - The type of the resource.
  - **Stack** (string) - The stack the resource belongs to.
  - **Target** (string) - The target environment for the resource.
  - **NativeID** (string) - The native identifier of the resource in the cloud provider.
  - **Managed** (boolean) - Indicates if the resource is managed by Formae.
  - **Properties** (object) - The properties of the resource.
- **Targets** (array) - A list of available targets.

#### Response Example
```json
{
  "Resources": [{
    "Label": "my-app-bucket",
    "Type": "AWS::S3::Bucket",
    "Stack": "production",
    "Target": "aws-us-east-1",
    "NativeID": "arn:aws:s3:::my-app-bucket",
    "Managed": true,
    "Properties": {}
  }],
  "Targets": []
}
```
```

--------------------------------

### List Policies API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve standalone policies with their attached stacks.

```APIDOC
## GET /api/v1/policies

### Description
Retrieve standalone policies with their attached stacks.

### Method
GET

### Endpoint
/api/v1/policies

### Response
#### Success Response (200)
- **Array of Policy Objects**: Each object contains 'Label', 'Type', 'AttachedStacks', and 'Config'.

#### Response Example
```json
[
  {
    "Label": "ttl-30d",
    "Type": "ttl",
    "AttachedStacks": ["dev-stack", "test-stack"],
    "Config": {...}
  }
]
```
```

--------------------------------

### List Resources via REST API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Queries the inventory of managed infrastructure resources. Allows filtering by resource type or stack.

```curl
curl -X GET "http://localhost:49684/api/v1/resources?query=type:AWS::S3::Bucket" \
  -H "Client-ID: my-client-001"

curl -X GET "http://localhost:49684/api/v1/resources?query=stack:production" \
  -H "Client-ID: my-client-001"
```

--------------------------------

### Force Synchronization API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Trigger immediate synchronization of resource state.

```APIDOC
## POST /api/v1/admin/synchronize

### Description
Trigger immediate synchronization of resource state.

### Method
POST

### Endpoint
/api/v1/admin/synchronize

### Response
#### Success Response (200)
- Returns 200 OK upon successful synchronization trigger.
```

--------------------------------

### List Stacks API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve all stacks in the inventory.

```APIDOC
## GET /api/v1/stacks

### Description
Retrieve all stacks in the inventory.

### Method
GET

### Endpoint
/api/v1/stacks

### Response
#### Success Response (200)
- **Array of Stack Objects**: Each object contains 'ID', 'Label', 'Description', and 'CreatedAt'.

#### Response Example
```json
[
  {
    "ID": "2NxgVh8WqTmJK9CvYpRsZD3EaFb",
    "Label": "my-app-stack",
    "Description": "Production application infrastructure",
    "CreatedAt": "2025-01-10T08:00:00Z"
  }
]
```
```

--------------------------------

### Manage Formae Commands via CLI

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Provides functionality to cancel in-progress infrastructure commands. Supports cancellation of the most recent command, specific IDs, or filtering by state.

```bash
formae cancel
formae cancel --query 'id:2NxgVh8WqTmJK9CvYpRsZD3EaFb'
formae cancel --query 'state:inprogress'
formae cancel --watch
```

--------------------------------

### List Targets API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Retrieve cloud targets (accounts/regions). Supports filtering by query parameters.

```APIDOC
## GET /api/v1/targets

### Description
Retrieve cloud targets (accounts/regions).

### Method
GET

### Endpoint
/api/v1/targets

#### Query Parameters
- **query** (string) - Optional - Filter targets by a query string (e.g., "namespace:AWS discoverable:true").

### Response
#### Success Response (200)
- **Array of Target Objects**: Each object contains 'Label', 'Namespace', 'Discoverable', and 'Config'.

#### Response Example
```json
[
  {
    "Label": "aws-us-east-1",
    "Namespace": "AWS",
    "Discoverable": true,
    "Config": {...}
  }
]
```
```

--------------------------------

### Retrieve Command Status via REST API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Fetches the status of infrastructure commands by ID or query parameters. Returns detailed resource update information.

```curl
curl -X GET "http://localhost:49684/api/v1/commands/2NxgVh8WqTmJK9CvYpRsZD3EaFb/status" \
  -H "Client-ID: my-client-001"

curl -X GET "http://localhost:49684/api/v1/commands/status?query=state:inprogress&max_results=10" \
  -H "Client-ID: my-client-001"

curl -X GET "http://localhost:49684/api/v1/commands/status" \
  -H "Client-ID: my-client-001"
```

--------------------------------

### Submit Destroy Command via REST API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Deletes infrastructure resources via the API. Can target specific files, resource queries, or simulation mode.

```curl
curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=destroy" \
  -F "simulate=false" \
  -F "file=@forma.json"

curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=destroy" \
  -F "query=type:AWS::S3::Bucket stack:my-stack"

curl -X POST http://localhost:49684/api/v1/commands \
  -H "Client-ID: my-client-001" \
  -F "command=destroy" \
  -F "simulate=true" \
  -F "query=label:my-resource"
```

--------------------------------

### Health Check API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Verify the API server is running.

```APIDOC
## GET /api/v1/health

### Description
Verify the API server is running.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
- Returns 200 OK if the server is running.
```

--------------------------------

### Cancel Commands

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Cancel in-progress commands. Can cancel the most recent command or commands matching a specific query.

```APIDOC
## POST /api/v1/commands/cancel

### Description
Cancel in-progress commands.

### Method
POST

### Endpoint
/api/v1/commands/cancel

### Parameters
#### Query Parameters
- **query** (string) - Optional - A query to select commands to cancel (e.g., 'id:2NxgVh8WqTmJK9CvYpRsZD3EaFb' or 'state:inprogress'). If omitted, the most recent command is cancelled.

### Request Example
```bash
# Cancel the most recent command
curl -X POST "http://localhost:49684/api/v1/commands/cancel" \
  -H "Client-ID: my-client-001"

# Cancel commands matching a query
curl -X POST "http://localhost:49684/api/v1/commands/cancel?query=id:2NxgVh8WqTmJK9CvYpRsZD3EaFb" \
  -H "Client-ID: my-client-001"
```

### Response
#### Success Response (202 Accepted)
- **CommandIds** (array) - A list of IDs of the commands that were cancelled.

#### Response Example
```json
{
  "CommandIds": ["2NxgVh8WqTmJK9CvYpRsZD3EaFb"]
}
```
```

--------------------------------

### Cancel Commands via REST API

Source: https://context7.com/platform-engineering-labs/formae/llms.txt

Cancels active commands remotely through the REST API. Supports targeting specific commands via query parameters.

```curl
curl -X POST "http://localhost:49684/api/v1/commands/cancel" \
  -H "Client-ID: my-client-001"

curl -X POST "http://localhost:49684/api/v1/commands/cancel?query=id:2NxgVh8WqTmJK9CvYpRsZD3EaFb" \
  -H "Client-ID: my-client-001"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.