> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formae.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start with an AI assistant

> Deploy your first infrastructure by describing what you want to an AI coding assistant.

This is the conversational path into formae. Instead of writing Pkl and running
CLI commands yourself, you describe what you want and your assistant does the
work: picking plugins, writing the forma, simulating, and applying.

You will install formae, connect your assistant, deploy something real, and tear
it down. It works the same on AWS, Azure, or GCP, because you tell the assistant
which cloud you are on.

<Note>
  Prefer to drive the CLI yourself? Follow the [Quick start](/documentation/get-started/quickstart)
  instead. Both end in the same place.
</Note>

<Steps>
  <Step title="Install formae">
    ```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
    /bin/bash -c "$(curl -fsSL https://hub.platform.engineering/get/formae.sh)"
    ```

    Add the binary to your `PATH`:

    <CodeGroup>
      ```bash zsh theme={"languages":{"custom":["/languages/pkl.json"]}}
      echo 'export PATH=/opt/pel/bin:$PATH' >> ~/.zshrc
      source ~/.zshrc
      ```

      ```bash bash theme={"languages":{"custom":["/languages/pkl.json"]}}
      echo 'export PATH=/opt/pel/bin:$PATH' >> ~/.bashrc
      source ~/.bashrc
      ```

      ```fish fish theme={"languages":{"custom":["/languages/pkl.json"]}}
      fish_add_path /opt/pel/bin
      ```
    </CodeGroup>

    Verify with `formae --version`.
  </Step>

  <Step title="Start the formae agent">
    Your assistant talks to the agent, so it needs to be running. Start it in its
    own terminal and leave it there:

    ```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
    formae agent start
    ```
  </Step>

  <Step title="Connect your assistant">
    Install the formae MCP server and skills in your client. Claude Code is a
    one-liner; other clients need the server registered manually.

    ```text theme={"languages":{"custom":["/languages/pkl.json"]}}
    /plugin marketplace add platform-engineering-labs/formae-marketplace
    /plugin install formae-mcp@formae-marketplace
    ```

    For Codex, OpenCode, Cursor, and other MCP clients, follow the
    [installation instructions](/documentation/guides/ai-coding-assistants#install).

    **Check the connection.** Ask your assistant:

    > Is my formae agent healthy?

    It should report live agent status. If it errors, the MCP server is not
    registered: see the setup guide above.
  </Step>

  <Step title="Make sure your cloud credentials are available">
    formae uses your existing cloud credentials. Set up whichever cloud you are
    deploying to:

    <Tabs>
      <Tab title="AWS">
        `aws configure`, or export `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
      </Tab>

      <Tab title="Azure">
        `az login`
      </Tab>

      <Tab title="GCP">
        Export `GCP_CREDENTIALS_FILE` (path to a service account key) or
        `GCP_CREDENTIALS_JSON` (the key itself).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Describe what you want">
    Now just ask. Name your cloud and what you want to deploy:

    > I want to deploy an S3 bucket to AWS in us-east-1 with formae.

    Your assistant uses the `formae-author` skill to work out which plugins you
    need, pull version-matched examples, write the forma file, and design the
    stack. It simulates the change and shows you what will be created before
    anything happens.

    Review the simulation, then tell it to go ahead:

    > Looks good, apply it.

    <Note>
      Your assistant always simulates before applying and asks before anything
      destructive. That behaviour is built into the skills, not something you have to
      remember to ask for.
    </Note>
  </Step>

  <Step title="Verify">
    Ask what you now have:

    > What resources do I have under management?

    It calls `list_resources` against the agent and shows you what formae is
    tracking. You can cross-check in your cloud console.
  </Step>

  <Step title="Clean up">
    > Destroy the stack you just created.

    Your assistant confirms first, then tears it down.
  </Step>
</Steps>

## What you just did

You never opened a Pkl file, but you now have a real forma in your project that
you own and can edit. The assistant is not a black box: it wrote IaC code you can
read, commit, and apply yourself with `formae apply`.

## What's next

<CardGroup cols={2}>
  <Card title="Write your first forma" href="/documentation/get-started/write-your-first-forma">
    Build a forma by hand to understand what your assistant generated.
  </Card>

  <Card title="AI coding assistants" href="/documentation/guides/ai-coding-assistants">
    All 19 skills, all 31 tools, and setup for every MCP client.
  </Card>

  <Card title="Core concepts" href="/documentation/concepts/label">
    Stacks, targets, resources, and formas.
  </Card>

  <Card title="Fix code drift" href="/documentation/guides/ai-coding-assistants">
    Ask your assistant to absorb out-of-band changes back into your code.
  </Card>
</CardGroup>