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

# formae connect

> Give a hosted formae installation permission to manage resources in a cloud account.

`formae connect` registers a cloud account against your hosted installation and
establishes the trust that lets the agent act in it. Trust is federated: the
installation exchanges a short-lived identity token for cloud credentials at
call time. No long-lived key is created, stored, or rotated.

This command needs a hosted profile. Sign in with `formae login --hosted` first.

<Note>
  If you work through an AI assistant, you do not run this command yourself. The
  formae MCP server drives the same flow through its own tools, and the
  [formae Cloud quickstart](/documentation/get-started/quickstart-cloud) walks
  through it.
</Note>

## Choosing how trust is established

Every cloud offers two ways in, and which one suits you depends on how much
access you are willing to give a CLI.

**Provision directly** when you have local cloud credentials and are content for
formae to use them once. formae creates the trust and registers it in a single
command, and the credentials are never stored.

**Register trust you established yourself** when you would rather not give a CLI
provisioning rights. You apply a small template in your own console or pipeline,
then hand formae the identifiers it produced. formae never holds a provisioning
credential on this path.

Registering trust you established yourself validates the shape of what you pass
and nothing more. It does not check that the identity exists, that it trusts the
formae issuer, or that it has any access. The first command that needs the trust
is what proves it, and it fails plainly if the trust is wrong.

## `formae connect aws`

Connects an AWS account.

| Flag                | Purpose                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `--account`         | The 12-digit account id. Always explicit, never inferred.                                                 |
| `--profile-aws`     | Provision directly using a local AWS shared-config profile.                                               |
| `--quick-create`    | Emit a CloudFormation console link to apply yourself.                                                     |
| `--role-arn`        | Register a role that already exists, from an applied stack or one you made.                               |
| `--provider-exists` | The account was connected before, so the shared OIDC provider exists and the stack creates only the role. |
| `--no-input`        | Disable prompts. Requires `--account` and one of the three methods above.                                 |

Run without flags to be asked for what is missing. The interactive quick-create
path prints the link and waits, so you can apply the stack and finish
registering in the same sitting.

## `formae connect azure`

Connects an Azure subscription.

| Flag               | Purpose                                                                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--subscription`   | The subscription id. Always explicit, never inferred from ambient credentials.                                                                                                      |
| `--tenant-id`      | The subscription's Entra tenant. Optional. When provisioning it is an authentication hint; when registering existing trust it is derived from the subscription if you leave it out. |
| `--client-id`      | Register a managed identity that already exists.                                                                                                                                    |
| `--location`       | Region for the managed identity's metadata record. Defaults to `eastus`. Provisioning only.                                                                                         |
| `--resource-group` | Resource group the connection resources live in. Defaults to `formae-ai`. Provisioning only.                                                                                        |
| `--no-input`       | Disable prompts.                                                                                                                                                                    |

Provisioning creates a user-assigned managed identity and grants it Contributor
and User Access Administrator on the subscription. That is near-owner access,
and it is what the agent needs to manage arbitrary infrastructure.

formae authenticates with whatever Azure credentials the machine already has:
environment variables, a managed identity, or an existing `az login` session. It
never opens a browser or starts a sign-in itself. With no usable credentials the
command stops and names both remedies rather than guessing.

When registering an existing Azure identity, supply the subscription and client
IDs. formae derives the tenant by asking Azure Resource Manager which directory
owns the subscription, without credentials. If that lookup fails, supply
`--tenant-id` explicitly.

### `formae connect azure template`

Prints an ARM template that establishes the same trust without any credential on
your machine.

Standard output is the template alone, so it redirects cleanly to a file.
Guidance goes to standard error, and leads with a link that opens the template
in the Azure portal with your installation's coordinates already filled in.
Deploy it in the portal or your own pipeline, then register what it created with
`formae connect azure --subscription <id> --client-id <c>`, taking the client
id from the deployment's outputs. The tenant is worked out from the
subscription, so only one value has to make the trip by hand; pass
`--tenant-id` as well if you would rather be explicit.

## `formae connect gcp`

Connects a GCP project.

| Flag                           | Purpose                                                                   |
| ------------------------------ | ------------------------------------------------------------------------- |
| `--project`                    | The project id. Always explicit, never inferred from ambient credentials. |
| `--workload-identity-provider` | Register federation you provisioned yourself.                             |
| `--allow-login`                | Permit the Google sign-in to open a browser even under machine output.    |
| `--no-input`                   | Disable prompts. On its own it also declines the Google sign-in.          |

Provisioning creates a workload identity pool and provider in the project and
grants formae editor access plus the ability to manage the project's IAM.

If the machine has no usable Google credentials, formae runs
`gcloud auth application-default login`, which opens a browser. Expect it. Under
machine output the sign-in is declined unless you pass `--allow-login`, so an
automated caller does not stall on a browser nobody will see.

## `formae connect list`

Lists the cloud accounts registered on this installation, with the trust
coordinate each one carries: a role for AWS, a workload identity provider for
GCP, a tenant and client id for Azure.

## Connecting more than one account

An installation can hold many accounts. Uniqueness is per installation, cloud,
and account, so the same account can be connected to two installations if you
mean it. Both then hold trust that can rewrite the other's access, so treat them
as sharing a trust domain rather than as isolated.