### Simple Configuration Example

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/deployment/applying-changes.md

An example YAML configuration file demonstrating two sites with four components each.

```yaml
sites:
  - name: site1
    components:
      - name: component1
        settings:
          replicas: 1
      - name: component2
        settings:
          replicas: 1
      - name: component3
        settings:
          replicas: 1
      - name: component4
        settings:
          replicas: 1
  - name: site2
    components:
      - name: component5
        settings:
          replicas: 1
      - name: component6
        settings:
          replicas: 1
      - name: component7
        settings:
          replicas: 1
      - name: component8
        settings:
          replicas: 1

```

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

### Example MACH composer configuration

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-6-create-mach-stack.md

This is an example of a MACH composer configuration file. Edit the paths and credentials to match your setup.

```yaml
---
mach_composer:
  version: 1.0.0
global:
  environment: test
  cloud: aws
  terraform_config:
    aws_remote_state:
    bucket: your-project-tst-tfstate
    key_prefix: mach
    region: eu-central-1
sites:
  - identifier: my-site-tst
    aws:
      account_id: ...
      region: eu-central-1
    commercetools:
      project_key: my-site-tst
      client_id: ...
      client_secret: ...
      scopes: manage_project:my-site-tst manage_api_clients:my-site-tst view_api_clients:my-site-tst
      languages:
        - en-GB
        - nl-NL
      currencies:
        - GBP
        - EUR
      countries:
        - GB
        - NL
    components:
      - name: api
components:
  - name: api
    source: ../components/api-component/terraform
    endpoints: 
      main: default
    version: dev

```

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

### Install Dependencies and Test Component Locally

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-5-create-component.md

After creating a component, run these commands to install its Node.js dependencies and execute local tests to verify its functionality.

```bash
$ yarn
$ yarn test
```

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

### Preview MACH Composer Documentation

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/README.md

Run this command to start a local server for previewing the documentation. Access the preview at http://localhost:8000/.

```bash
task preview
```

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

### MACH composer Nix Overlay Example

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/README.md

Example of how to create a Nix overlay to manage MACH composer packages, ensuring compatibility with your system configuration.

```nix
let
  mach-composer-overlay = final: prev: {
    mach-composer = mach-composer.packages.${system}.mach-composer;
  };
  pkgs = import nixpkgs {
    inherit system;
    config = {
      allowUnfree = true;
    };

    overlays = [
      mach-composer-overlay
    ];
  };

```

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

### Mach Composer Configuration Example

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/syntax/mach_composer.md

This is an example of the main mach-composer configuration file. It specifies the schema version and the location of the variables file.

```yaml
mach_composer:
  version: 1
  variables_file: variables.yml
```

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

### MACH Composer Configuration Example with Variables

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/syntax/index.md

An example of a MACH Composer configuration file showcasing the use of environment variables, component output references, and variable file values. This illustrates how to keep configurations DRY and manage sensitive data.

```yaml
mach_composer:
  version: 1
global:
  environment: ${env.MACH_ENVIRONMENT}
  cloud: aws
sites:
  - identifier: my-site
    aws:
      account_id: 1234567890
      region: eu-central-1
    endpoints:
      public: api.tst.mach-example.net
    components:
      - name: infra
      - name: payment
        variables:
          sns_topic: ${components.infra.sns_topic_arn}
        secrets:
          stripe_secret_key: ${var.stripe_secret}
```

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

### Example Site Component Configuration

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/syntax/site.md

Defines components for a site, including their names, variables, secrets, and dependencies. Use this to specify deployable units and their configurations.

```yaml
components:
  - name: api-extensions
    variables:
      ORDER_PREFIX: mysitetst
    depends_on:
      - order-mailer
  - name: order-mailer
    variables:
      FROM_EMAIL: mach@example.com
    secrets:
      SENDGRID_API_KEY: my-api-token
    store_variables:
      brand-a:
        FROM_EMAIL: mach@brand-a.com
      other-brand:
        FROM_EMAIL: mach@other-brand.com

```

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

### Install MACH Composer CLI

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/README.md

Use this command to install the MACH composer CLI. Ensure you have the task runner installed.

```bash
task install
```

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

### Install Terraform on Windows

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/step-1-installation.md

Installs Terraform on Windows using Chocolatey. Ensure Chocolatey is installed before running.

```powershell
choco install terraform
```

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

### Component Configuration Wizard Input

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-5-create-component.md

Example input values for the component bootstrapping wizard. Customize these based on your project's requirements, especially the S3 bucket name for Lambda repositories.

```text
Cloud environment (aws, azure) [aws]: aws
Language (python, node) [node]: node
Name [example-name]: api
Description [Api component]:
Directory name [api-component]:
Uses an HTTP endpoint? [Y/n]: y
Include GraphQL support? [Y/n]: y
Uses commercetools? [Y/n]: n
Use Sentry? [y/N]: n
Lambda repository S3 bucket: your-project-lambdas
New component api-component created 🎉
```

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

### Install MACH composer with Shell Script

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/README.md

Run this command to install the latest MACH composer release. Ensure $HOME/bin is in your PATH.

```bash
$ curl -sfL https://raw.githubusercontent.com/mach-composer/mach-composer-cli/f08424b1bc38086696767a1ce05e1b0fbb199326/scripts/install-mach-composer.sh | bash
```

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

### Example MACH Composer YAML Configuration

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/README.md

This is a sample YAML file demonstrating the structure for defining global settings, site-specific configurations, and component details within MACH Composer.

```yaml
---
mach_composer:
  version: 1
global:
  environment: test
  cloud: aws
  terraform_config:
    aws_remote_state:
      bucket: mach-tfstate-tst
      key_prefix: mach-composer-tst
      region: eu-central-1
sites:
  - identifier: my-site
    aws:
      account_id: 1234567890
      region: eu-central-1
    endpoints:
      public: api.tst.mach-example.net
    commercetools:
      project_key: my-site-tst
      client_id: ...
      client_secret: ...
      scopes: manage_project:my-site-tst manage_api_clients:my-site-tst view_api_clients:my-site-tst
      token_url: https://auth.europe-west1.gcp.commercetools.com
      api_url: https://api.europe-west1.gcp.commercetools.com
      project_settings:
        languages:
          - en-GB
          - nl-NL
        currencies:
          - GBP
          - EUR
        countries:
          - GB
          - NL
    components:
      - name: payment
        variables:
          STRIPE_ACCOUNT_ID: 0123456789
        secrets:
          STRIPE_SECRET_KEY: secret-value
components:
  - name: payment
    source: git::ssh://git@github.com/your-project/components/payment-component.git//terraform
    endpoints:
      main: public
    version: e638e57

```

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

### Mach Composer Init Command Structure

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_init.md

This is the base command for initializing site directories and Terraform files. Use this command to start a new MACH composer project.

```bash
mach-composer init [flags]
```

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

### Install MACH composer on Windows (Experimental)

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/step-1-installation.md

Installs MACH composer using Chocolatey on Windows. Note that Windows support is experimental and manual installation via GitHub releases is recommended for the latest version.

```powershell
choco install mach-composer
```

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

### Example MACH Composer Configuration File

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/azure/step-5-create-mach-stack.md

This YAML file defines the structure and settings for a MACH composer stack, including environment, cloud provider details, site-specific configurations, and component definitions.

```yaml
---
mach_composer:
  version: 1.0.0
global:
  environment: test
  cloud: azure
  terraform_config:
    azure_remote_state:
      resource_group: my-shared-rg
      storage_account: mysharedsaterra
      container_name: tfstate
      state_folder: test
  azure:
    tenant_id: e180345a-b3e1-421f-b448-672ab50d8502
    subscription_id: 086bd7e7-0755-44ab-a730-7a0b8ad4883f
    region: westeurope
sites:
  - identifier: my-site
    endpoints:
      main: api.tst.mach-example.net
    commercetools:
      project_key: my-site-tst
      client_id: ...
      client_secret: ...
      scopes: manage_project:my-site-tst manage_api_clients:my-site-tst view_api_clients:my-site-tst
      languages:
        - en-GB
        - nl-NL
      currencies:
        - GBP
        - EUR
      countries:
        - GB
        - NL
    components:
      - name: payment
        variables:
          STRIPE_ACCOUNT_ID: 0123456789
        secrets:
          STRIPE_SECRET_KEY: secret-value
components:
  - name: payment
    source: git::ssh://git@github.com/your-project/components/payment-component.git//terraform
    endpoints:
      main: main
    version: e638e57

```

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

### Example Commercetools Configuration Block

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/plugins/commercetools.md

This comprehensive YAML block illustrates a full Commercetools configuration within MACH composer, including project details, localization settings, and definitions for channels and stores.

```yaml
commercetools:
  project_key: nl-mach-tst
  client_id: ixwVv7T3rnmJ
  client_secret: dElymMZvDqW3X5RLASMS
  scopes: manage_project:nl-mach-tst manage_api_clients:nl-mach-tst view_api_clients:nl-mach-tst
  languages:
      - en-GB
      - nl-NL
  currencies:
      - GBP
      - EUR
  countries:
      - GB
      - IE
      - NL
  channels:
    - key: INV
      roles:
        - InventorySupply
      name:
        en-GB: Inventory
      description:
        en-GB: Main inventory channel
    - key: DIST-EUR
      roles:
        - ProductDistribution
      name:
        en-GB: Europe Distribution
      description:
        en-GB: Europe distribution channel
  stores:
      - key: uk-store
        name:
          en: UK store
        languages:
          - en-GB
        distribution_channels:
          - DIST-EUR
        inventory_channels:
          - INV
      - key: nl-store
        name:
          en: NL store
        languages:
          - nl-NL
        distribution_channels:
          - DIST-EUR
        inventory_channels:
          - INV
```

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

### Install Terraform using tfenv

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/step-1-installation.md

Installs the latest version of Terraform using the tfenv version manager. This is recommended for macOS and Linux users.

```bash
$ tfenv install latest
```

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

### Install MACH Composer CLI with Homebrew

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/development/environment.md

Use this command to install the MACH composer CLI on macOS and Linux systems via Homebrew.

```bash
brew tap mach-composer/mach-composer
brew install mach-composer
```

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

### Generate Project Graph with Graphviz

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_graph.md

This command generates the project's graph in DOT language and pipes it to the 'dot' command to create a PNG image. Ensure Graphviz is installed.

```bash
mach-composer graph -f main.yml | dot -Tpng -o image.png
```

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

### Example Site Endpoint Definitions

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/syntax/site.md

Defines endpoint URLs for a site. These can be simple URLs or complex configurations with zone and AWS/Azure specific settings.

```yaml
endpoints:
  main: api.tst.mach-example.net
  services: services.tst.mach-example.net

```

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

### MACH composer Configuration Example

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/cloud/component-registry.md

This YAML configuration shows how components are defined in MACH composer, including their name, source repository, version, and branch. This structure is used by the CLI to manage deployments.

```yaml
components:
  - name: api-service
    source: git::https://github.com/mach-composer/mcc-api-service.git//terraform
    version: "66e74f4"
    branch: main

  - name: auth-service
    source: git::https://github.com/mach-composer/mcc-auth-service.git//terraform
    version: "7e746bb"
    branch: main
```

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

### Log in to MACH composer Cloud

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/cloud/index.md

Execute this command to log in or register with MACH composer Cloud. It uses GitHub for authentication. Ensure you have the latest version of MACH composer installed.

```console
$ mach-composer cloud login
```

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

### Define Components in Mach Composer Configuration

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/syntax/component.md

Example of how to define multiple components, including their source, version, and paths, within the Mach Composer configuration file. This demonstrates the structure for integrating external component definitions.

```yaml
components:
  - name: api-extension-products
    source: git::ssh://git@git.labdigital.nl/mach-components/api-extensions-component.git//products/terraform
    version: 3b8ab91
    paths:
      - products/terraform
  - name: api-extension-orders
    source: git::ssh://git@git.labdigital.nl/mach-components/api-extensions-component.git//orders/terraform
    version: 3b8ab91
    paths:
      - orders/terraform
  - name: ct-products-types
    source: git::ssh://git@git.labdigital.nl/mach-components/ct-product-types.git//terraform
    version: 1.4.0
    integrations:
      - commercetools
```

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

### AWS IAM Configuration for Component Upload

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-5-create-component.md

Example configuration for the `~/.aws/config` file to specify an AWS profile for uploading components. Ensure the `role_arn` points to the correct IAM role for your service account.

```conf
[profile your-project-srv]
source_profile = default
role_arn = arn:aws:iam::<service-account-id>:role/admin
```

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

### AWS Deployment Workflow with MACH Composer

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/ci/github.md

This GitHub Actions workflow demonstrates how to plan and deploy infrastructure using MACH composer on AWS. It includes steps for checking out code, preparing credentials, installing Terraform and MACH composer, configuring AWS credentials, planning the deployment, storing the plan, and applying the deployment. Ensure AWS credentials and repository tokens are securely configured in GitHub secrets.

```yaml
name: Deploy Test
on:
  pull_request:
    types: [opened, synchronize, closed]
    paths:
      - 'main.yml'

concurrency: test

env:
  TF_PLUGIN_CACHE_DIR: ${{ github.workspace }}/.terraform.d/plugin-cache
  MACH_COMPOSER_VERSION: 2.5.4
  AWS_DEPLOY_ROLE: arn:aws:iam::<AWS_ACCOUNT_ID>:role/mach-deploy-role
  AWS_DEPLOY_REGION: "eu-west-1"
  AWS_PLAN_BUCKET: "bucket name to store terraform plans"
  CONFIG_FILE: "main.yml"

jobs:
  plan:
    runs-on: ubuntu-latest
    if: github.event.pull_request.merged != true && github.base_ref == 'main'
    permissions:
      id-token: write # This is required for requesting the JWT
      contents: read  # This is required for actions/checkout
      pull-requests: write
    steps:
      - uses: actions/checkout@v3

      - name: Prepare credentials
        run: |
          git config --global url."https://oauth2:${{ secrets.ORG_REPO_TOKEN }}@github.com".insteadOf https://github.com

      - name: Install terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.1.7

      - name: Create Terraform Plugins Cache Dir
        run: mkdir --parents $TF_PLUGIN_CACHE_DIR

      - name: Cache Terraform Plugins
        uses: actions/cache@v2
        with:
          path: ${{ env.TF_PLUGIN_CACHE_DIR }}
          key: ${{ runner.os }}-terraform-${{ hashFiles('**/.terraform.lock.hcl') }}

      - name: Install MACH composer
        uses: mach-composer/setup-mach-composer@main
        with:
          version: ${{ env.MACH_COMPOSER_VERSION }}

      - name: Install sops
        uses: mdgreenwald/mozilla-sops-action@v1.4.1

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: ${{ env.AWS_DEPLOY_ROLE }}
          aws-region: ${{ env.AWS_DEPLOY_REGION }}

      - name: MACH composer plan
        uses: mach-composer/plan-action@main
        with:
          filename: ${{ env.CONFIG_FILE }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Store terraform plan
        run: aws s3 cp --sse AES256 --recursive --exclude '*' --include "deployments/*/terraform.plan" . s3://${{ env.AWS_PLAN_BUCKET }}/${{ github.event.pull_request.number }}/


  deploy:
    runs-on: ubuntu-latest
    if: github.event.pull_request.merged == true && github.base_ref == 'main'
    environment:
      name: test
      url: "<your env url>"
    permissions:
      id-token: write # This is required for requesting the JWT
      contents: read  # This is required for actions/checkout
    steps:
      - uses: actions/checkout@v3

      - name: Prepare credentials
        run: |
          git config --global url."https://oauth2:${{ secrets.ORG_REPO_TOKEN }}@github.com".insteadOf https://github.com

      - name: Install terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.1.7

      - name: Create Terraform Plugins Cache Dir
        run: mkdir --parents $TF_PLUGIN_CACHE_DIR

      - name: Cache Terraform Plugins
        uses: actions/cache@v2
        with:
          path: ${{ env.TF_PLUGIN_CACHE_DIR }}
          key: ${{ runner.os }}-terraform-${{ hashFiles('**/.terraform.lock.hcl') }}

      - name: Install MACH Composer
        uses: mach-composer/setup-mach-composer@main
        with:
          version: ${{ env.MACH_COMPOSER_VERSION }}

      - name: Install sops
        uses: mdgreenwald/mozilla-sops-action@v1.4.1

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: ${{ env.AWS_DEPLOY_ROLE }}
          aws-region: ${{ env.AWS_DEPLOY_REGION }}

      - name: Retrieve terraform plan
        run: aws s3 cp --sse AES256 --recursive s3://${{ env.AWS_PLAN_BUCKET }}/${{ github.event.pull_request.number }}/ .

      - name: Run MACH Composer apply
        run: mach-composer apply --auto-approve -f ${{ env.CONFIG_FILE }}

      - name: Cleanup terraform plan
        run: aws s3 rm --recursive s3://${{ env.AWS_PLAN_BUCKET }}/${{ github.event.pull_request.number }}/

```

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

### Install Specific MACH composer Version with Shell Script

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/README.md

Set the VERSION environment variable before running the install script to get a specific release.

```bash
$ export VERSION=v2.20.0
$ curl -sfL https://raw.githubusercontent.com/mach-composer/mach-composer-cli/refs/heads/main/scripts/install-mach-composer.sh | bash
```

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

### Usage of Build Script

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/components/lifecycle/first-stage.md

Demonstrates how to execute the package and upload actions using the build script.

```bash
$ ./build.sh package
$ ./build.sh upload
```

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

### Run Component and its Dependencies with --filter

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/cli/filtering-commands.md

Use the 'site-name/component-name...' syntax to run a specific component in a site and all its dependencies.

```bash
mach-composer apply --filter site-1/component-1...
```

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

### Run Site and Dependent Components with --filter

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/cli/filtering-commands.md

Use the 'site-name...' syntax to run a site and all its dependent components.

```bash
mach-composer apply --filter site-1...
```

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

### Bootstrap a MACH Component

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-5-create-component.md

Use this command to initiate the creation of a new MACH component. Follow the interactive wizard to configure its settings.

```bash
$ mach-composer bootstrap component
```

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

### Bootstrap a MACH Component

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/azure/step-4-create-component.md

Use this command to initiate the creation of a new MACH component. Follow the on-screen wizard to configure its details. This component can then be pushed to a Git repository.

```bash
mach-composer bootstrap component
```

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

### Example Terraform Output for Component Reference

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/syntax/index.md

An example of Terraform outputs defined within a component. These outputs can be referenced in the MACH Composer configuration using the `${component.<component-name>.<output-value>}` syntax.

```terraform
# outputs.tf

output "sqs_queue" {
  value = {
    id  = aws_sqs_queue.email_queue.id
    arn = aws_sqs_queue.email_queue.arn
  }
}
```

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

### mach-composer version Help Options

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_version.md

Displays help information for the version command. Use this to see available flags specific to the version command.

```bash
-h, --help   help for version
```

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

### Run a Site with --filter

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/cli/filtering-commands.md

Use the --filter flag followed by the site name to run all components within that site.

```bash
mach-composer apply --filter site-1
```

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

### Terraform Configuration - Required Version

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/azure/step-3-setup-azure.md

Specifies the minimum required Terraform version for the project. Ensure your Terraform installation meets this requirement.

```terraform
terraform {
  required_version = ">= 0.14.0"
}
```

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

### Preview Deployment Graph

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/deployment/applying-changes.md

Outputs a trimmed-down version of the dependency graph, showing only independently deployable components. Useful for understanding deployment order.

```bash
mach-composer graph --deployment
```

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

### Deploy MACH stack with aws-vault

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-6-create-mach-stack.md

Deploy your MACH stack using `aws-vault` for secure credential management. This command assumes you have `aws-vault` installed and configured.

```bash
aws-vault exec your-project-tst -- mach-composer apply
```

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

### List Projects Command

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_list-projects.md

Use this command to list all projects. Specify the organization key to target a specific organization.

```bash
mach-composer cloud list-projects [flags]
```

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

### Terraform Variables for AWS Account Setup

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-4-setup-aws-site.md

Define input variables for AWS account ID, name, and region. These are used to configure the Terraform resources for a specific site.

```terraform
variable "aws_account_id" {
    type = string
}

variable "name" {
    type = string
}

variable "region" {
  default = "eu-central-1"
}
```

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

### Build and Package Component

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/azure/step-4-create-component.md

Execute these commands to build and package a component, particularly if it contains serverless functions. The output is prepared for upload to an artifact repository.

```bash
./build.sh package
```

```bash
./build.sh upload
```

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

### Initialize and Apply Terraform

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/azure/step-3-setup-azure.md

Initializes the Terraform working directory and applies the configuration to create or update resources.

```bash
$ terraform init
$ terraform apply
```

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

### Terraform Initialization and Apply Commands

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-4-setup-aws-site.md

Commands to initialize the Terraform project and apply the configuration for a specific environment using a variable file.

```bash
$ terraform init -var-file=envs/tst.tfvars
$ terraform apply -var-file=envs/tst.tfvars
```

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

### Terraform Initialization and Apply Commands

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-3-setup-aws-services.md

Commands to initialize Terraform, apply the configuration, and migrate the local state to the remote backend. The '-force-copy' flag is used for the one-time migration of the local state file to the S3 bucket.

```bash
$ terraform init
$ terraform apply
```

```bash
$ terraform init -force-copy
```

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

### Convenience Script for Component Migration

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/state/migration.md

A bash script to automate the manual migration steps. It takes the site directory and component name as arguments. Use with caution.

```bash
#!/bin/bash

if [ -n "$1" ]; then
  echo "Using $1 as the site directory."
else
  echo "Provide the site directory. This generally is in the format of ./deployments/main/<site-name>."
  exit 1
fi

if [ -n "$2" ]; then
  echo "Using $2 as the component"
else
  echo "Provide the component name"
  exit 1
fi


mach-composer generate -f main.yaml
mach-composer init -f main.yaml

cd ./$1 || exit

terraform state pull > terraform.tfstate

cd ./$2 || exit

terraform state pull > terraform.tfstate

cd ../

terraform state mv --state=terraform.tfstate --state-out=./"$2"/terraform.tfstate "module.$2" "module.$2"

terraform state push terraform.tfstate

cd ./"$2" || exit

terraform state push terraform.tfstate
```

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

### Package and Deploy Component on AWS (Node.js)

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/ci/github.md

A GitHub Actions workflow to package a Node.js Lambda function and upload it to an S3 bucket. It handles dependency installation, packaging, and AWS credential configuration.

```yaml
name: Package and upload

on:
  push:
    branches:
      - main

env:
  PACKAGE_NAME: my-component
  AWS_BUCKET_NAME: my-lambda-bucket

jobs:
  package:
    name: Package Lambda function
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Artifact Name
        id: artifact-name
        run: echo "::set-output name=artifact::$(echo $PACKAGE_NAME-${GITHUB_SHA:0:7}.zip)"

      - name: Use Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: Cache modules
        uses: actions/cache@v2
        with:
          path: '**/node_modules'
          key: ${{ runner.os }}-modules-${{ hashFiles('**/yarn.lock') }}

      - name: Install dependencies
        run: yarn

      - name: Package
        uses: dragonraid/sls-action@v1.2
        with:
          args: --stage prod package

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.MACH_ARTIFACT_AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.MACH_ARTIFACT_AWS_SECRET_ACCESS_KEY }}
          aws-region: eu-central-1

      - name: Upload
        run: aws s3 cp .serverless/${{ env.PACKAGE_NAME }}.zip s3://${{ env.AWS_BUCKET_NAME }}/${{ steps.artifact-name.outputs.artifact }}
```

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

### List Projects Options

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_list-projects.md

Available options for the list-projects command, including help and organization targeting.

```bash
-h, --help help for list-projects
    --organization string   The organization key to use
```

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

### Include YAML Files in Configuration

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/syntax/index.md

Demonstrates how to include other YAML files within the main configuration using the `$ref` syntax. This is useful for managing component definitions separately.

```yaml
---
mach_composer: ...
global: ...
sites: ...
components:
  $ref: _components.yaml
```

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

### Bootstrap MACH composer configuration

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-6-create-mach-stack.md

Run this command to create a new MACH composer configuration file. This file serves as input for MACH composer.

```bash
mach-composer bootstrap config
```

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

### Create API Client Options

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_create-api-client.md

These are the specific options for the create-api-client command. The organization and project flags are required to identify your cloud resources.

```bash
  -h, --help                  help for create-api-client
      --organization string   Organization key
      --project string        Project key
```

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

### Define Default Endpoint for a Component

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/stack/aws.md

Use the 'default' endpoint type when a component requires a standard API Gateway setup without custom routing configurations. This simplifies deployment for components with a single, primary endpoint.

```yaml
components:
  - name: payment
    source: git::ssh://git@github.com/your-project/components/payment-component.git//terraform
    endpoints:
      public: default
    version: ....
```

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

### Override Plugin Behavior with Custom Repository

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/plugins/index.md

To override a plugin's behavior, fork its repository, implement changes, and configure MACH composer to use your custom source. Ensure your release pipeline generates an installable artifact.

```yaml
mach_composer:
  plugins:
    aws:
      source: my-org/my-fork-of-aws
      version: 0.1.0
```

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

### Terraform Plan and Apply

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/state/migration.md

Final commands to verify the migration by planning and applying the changes. Run 'terraform plan' from the root directory and 'terraform apply' after confirming the plan.

```bash
cd ../../..
terraform plan
```

```bash
terraform apply
```

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

### Package Python Function for AWS

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/components/lifecycle/first-stage.md

This bash script packages a Python function into a ZIP file for AWS, including dependencies installed via pip and the handler file. It tags the artifact with a short Git commit hash.

```bash
VERSION=$(shell git rev-parse --short HEAD 2>/dev/null || echo "dev" )
NAME=your-component-$VERSION
ARTIFACT_NAME=$NAME.zip

python -m pip install dist/*.whl -t ./build
cp handler.py ./build
cd build && zip -9 -r $ARTIFACT_NAME .
```

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

### Python Component Deployment CI Pipeline

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/ci/azure_devops.md

This CI pipeline configuration is for deploying Python-based components. It installs Azure Functions Core Tools, sets up the Python environment, runs tests, packages the application, and uploads it using Azure CLI.

```yaml
trigger:
- master

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: |
    curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
    sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/microsoft.gpg
    sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-ubuntu-$(lsb_release -cs)-prod $(lsb_release -cs) main" > /etc/apt/sources.list.d/dotnetdev.list'
    sudo apt-get update
    sudo apt-get install azure-functions-core-tools-3
  displayName: Install core tools

- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.8'
  displayName: 'Use Python 3.8'

- script: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
  displayName: 'Install dependencies'

- script: |
    pip install pytest pytest-azurepipelines
    pytest
  displayName: 'Test'

- script: ./azure_package.sh package
  displayName: Package

- task: AzureCLI@2
  displayName: Upload
  inputs:
    azureSubscription: '<azure-service-connection>'
    scriptType: bash
    scriptPath: ./azure_package.sh
    arguments: upload

```

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

### Initialize Terraform with MACH Composer

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/README.md

Run `terraform init` through MACH Composer to initialize the Terraform backend without making any changes.

```console
mach-composer terraform init

```

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

### Deploy MACH Composer Stack

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/azure/step-5-create-mach-stack.md

Run this command to deploy your current MACH composer configuration. This applies all defined infrastructure and configurations.

```bash
$ mach-composer apply
```

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

### List API Clients Options

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_list-api-clients.md

Options available for the list-api-clients command, including organization and project keys.

```bash
--organization string   Organization key
```

```bash
--project string        Project key
```

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

### Run MACH Composer Apply using Docker

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/azure/step-5-create-mach-stack.md

Invoke MACH composer by running its Docker image. Mount your current directory to `/code` and ensure necessary environment variables for cloud provider authentication are provided.

```bash
$ docker run --rm --volume $(pwd):/code docker.pkg.github.com/mach-composer/mach-composer-cli/mach apply
```

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

### Run a Specific Component in a Site with --filter

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/cli/filtering-commands.md

Target a specific component within a specific site by using the 'site-name/component-name' format with the --filter flag.

```bash
mach-composer apply --filter site-1/component-1
```

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

### Create Organization Command Options

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_create-organization.md

These are the specific options available for the create-organization command, including help, key, and name flags.

```bash
mach-composer cloud create-organization [flags]
```

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

### List Components Options

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_list-components.md

These are the specific options for the list-components command. The organization and project flags are essential for targeting your components.

```bash
-h, --help                  help for list-components
      --organization string   Organization key
      --project string        Project key
```

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

### mach-composer cloud create-component Options

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_create-component.md

These are the specific options for the create-component command. Use --organization and --project to specify the target organization and project for the new component.

```bash
  -h, --help                  help for create-component
      --organization string   Organization key
      --project string        Project key
```

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

### Register Component Version Command

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_register-component-version.md

Use this command to register a new version for an existing component. Specify the component name, version, and optional flags for customization.

```bash
mach-composer cloud register-component-version [name] [version] [flags]
```

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

### Basic Site and Component Definition

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/deployment/applying-changes.md

Defines two sites, 'my-site' and 'my-other-site', each with a 'my-component' that depends on parent and grandparent components. No global deployment type is set, so the default 'site' type is inherited.

```yaml
mach_composer:
  version: 1
  plugins: { }
  # Note no global deployment type set, so default `site` is inherited by all components

global:
  cloud: ""
  environment: test
  terraform_config:
    remote_state:
      plugin: local
      path: ./state
sites:
  - identifier: my-site
    components:
      - name: my-component
        variables:
          parent_url: ${component.my-parent-component.url}
          other_parent_url: ${component.my-other-parent-component.url}
      - name: my-parent-component
        variables:
          grandparent_url: ${component.my-grandparent-component.url}
      - name: my-other-parent-component
        variables:
          grandparent_url: ${component.my-grandparent-component.url}
      - name: my-grandparent-component
  - identifier: my-other-site
    components:
      - name: my-component
        variables:
          parent_url: ${component.my-parent-component.url}
          other_parent_url: ${component.my-other-parent-component.url}
      - name: my-parent-component
        variables:
          grandparent_url: ${component.my-grandparent-component.url}
      - name: my-other-parent-component
        variables:
          grandparent_url: ${component.my-grandparent-component.url}
      - name: my-grandparent-component

components:
  - name: my-component
    source: ./my-component/terraform
    version: "v1.0.0"
    branch: main
  - name: my-parent-component
    source: ./modules/application
    version: "v1.2.1"
    branch: main
  - name: my-other-parent-component
    source: ./modules/application
    version: "v1.2.1"
    branch: main
  - name: my-grandparent-component
    source: ./modules/application
    version: "v2.0.0"
    branch: main

```

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

### Login to Azure CLI

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/azure/step-3-setup-azure.md

Logs you into your Azure subscription via the CLI. Follow the prompts to authenticate.

```bash
$ az login
```

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

### mach-composer cloud create-project Options

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_create-project.md

Specific options available for the create-project command, such as specifying the organization.

```bash
-h, --help                  help for create-project
      --organization string   organization
```

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

### Create a MACH composer Cloud Project

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/cloud/getting-started.md

Create a new project within your MACH composer Cloud organization. This project will house your components.

```bash
% mach-composer cloud create-project my-project "My Project" --organization my-org
Created new project: my-project
```

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

### Create Azure KeyVault

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/ci/azure_devops.md

Use this Azure CLI command to create a KeyVault for storing pipeline credentials. Ensure the name is unique and the resource group exists.

```bash
$ az keyvault create --name myprefix-devops-secrets --resource-group my-shared-we-rg
```

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

### mach-composer cloud create-component Command Usage

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_create-component.md

This is the basic usage of the create-component command. Provide the component name and optionally a key. Flags can be used to specify organization, project, and output settings.

```bash
mach-composer cloud create-component [name] [key] [flags]
```

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

### POST /cloud/create-project

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_create-project.md

Creates a new project in the Mach Composer Cloud.

```APIDOC
## POST /cloud/create-project

### Description
Creates a new project in the Mach Composer Cloud.

### Method
POST

### Endpoint
/cloud/create-project

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique key for the project.
- **name** (string) - Required - The name of the project.

#### Query Parameters
- **organization** (string) - Optional - The organization to associate the project with.
- **output** (string) - Optional - The output type. One of: console, json (default "console").
- **quiet** (boolean) - Optional - Quiet output. This is equal to setting log levels to error and higher.
- **strip-logs** (boolean) - Optional - Strip all context from the logs.
- **verbose** (boolean) - Optional - Verbose output. This is equal to setting log levels to debug and higher.

### Request Example
```json
{
  "key": "my-project-key",
  "name": "My Awesome Project",
  "organization": "my-org"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the project was created successfully.

#### Response Example
```json
{
  "message": "Project 'My Awesome Project' created successfully."
}
```
```

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

### Package Serverless Function

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/components/lifecycle/first-stage.md

Use this command when developing serverless functions locally to package your function for deployment.

```bash
$ serverless package
```

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

### Mixed Deployment Types for Sites

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/concepts/deployment/applying-changes.md

Demonstrates a configuration where 'my-site' uses the default 'site' deployment type for all its components, while 'my-other-site' has all its components deployed independently as 'site-component' type.

```yaml
sites:
  - identifier: my-site
    components:
    # Etc...
  - identifier: my-other-site
    deployment:
      type: site-component
    components:
    # Etc...

```

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

### Mach Composer Init Command Flags

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_init.md

These flags allow customization of the init command. Use the --file flag to specify a YAML configuration file, or --site to target a specific site. The --output-path flag controls where generated files are stored.

```bash
-b, --buffer               Whether logs should be buffered and printed at the end of the run
```

```bash
-f, --file string          YAML file to parse. (default "main.yml")
```

```bash
--filter stringArray   Run only nodes matching the filter expression
```

```bash
-g, --github               Whether logs should be decorated with github-specific formatting
```

```bash
-h, --help                 help for init
```

```bash
--ignore-version       Skip MACH composer version check
```

```bash
--output-path string   Outputs path to store the generated files. (default "deployments")
```

```bash
-s, --site string          Site to parse. If not set parse all sites.
```

```bash
--var-file string      Use a variable file to parse the configuration with.
```

```bash
-w, --workers int          The number of workers to use (default 1)
```

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

### Plan Terraform Changes with MACH Composer

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/README.md

Execute the `plan` command to preview the Terraform changes that will be applied.

```console
mach-composer plan

```

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

### Package Component for Deployment

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/tutorial/aws/step-5-create-component.md

This script command packages a component, typically a serverless function, for deployment to a component registry. Ensure you have the necessary build scripts in your component's root directory.

```bash
$ ./build.sh package
```

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

### List Components Command

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_list-components.md

Use this command to list components within your Mach Composer Cloud. Specify the organization and project keys for targeted results.

```bash
mach-composer cloud list-components [flags]
```

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

### mach-composer cloud create-api-client Command

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_create-api-client.md

Use this command to create an API client for your Mach Composer cloud project. Specify the organization and project keys.

```bash
mach-composer cloud create-api-client [flags]
```

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

### List API Clients Command

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/reference/cli/mach-composer_cloud_list-api-clients.md

Use this command to list existing API clients for a given organization and project. The secret is not included in the output.

```bash
mach-composer cloud list-api-clients [flags]
```

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

### Run a Component with --filter

Source: https://github.com/mach-composer/mach-composer-cli/blob/main/docs/src/howto/cli/filtering-commands.md

Use the --filter flag followed by the component name to run a specific component.

```bash
mach-composer apply --filter component-1
```