> ## 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.

# Manage profiles

> Switch the formae CLI between environments with named configuration profiles.

A profile is a complete formae configuration for one environment: the agent
endpoint the CLI talks to, plus targets, credentials, and any other settings.
Profiles let you point the CLI at different environments (local-dev, staging,
prod) without hand-editing or swapping config files.

## You start with a default profile

A fresh install ships with a ready-to-use `default` profile pointed at a local
agent. So if you [run the agent on your machine](/documentation/guides/install-agent)
with `formae agent start`, the CLI already reaches it, with no profile setup at
all. See what you have:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae profile list
```

The active profile is marked with `*`; on a clean install that is `default`.

## Edit the default profile

To point the default profile somewhere else, or add settings, open it in your
editor:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae profile edit
```

With no name, `edit` opens the active profile. A profile is a Pkl file; its
`cli.api.url` is the agent endpoint the CLI connects to (a local agent by
default).

## Create a profile for another environment

Once you have more than one environment (say a local agent and a bootstrapped one
in AWS), give each its own profile:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae profile create staging
formae profile edit staging
```

`create` starts from a minimal template; `edit` opens it so you can set the agent
URL and any other settings. When you
[install an agent with bootstrap](/documentation/guides/install-agent), the
installer writes this profile for you.

## Switch between environments

One profile is active at a time, and it applies to every command that connects to
the agent (`apply`, `destroy`, `status`, `inventory`, and the rest). Switch it
with:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae profile use staging
```

To target a different environment for a single command without changing the
active one, pass `--profile`:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae apply --mode reconcile --profile prod ./infra.pkl
formae status --profile prod
```

`--profile` is mutually exclusive with `--config`: a profile is a config source,
so passing both is an error.

## Where profiles live

Profiles are stored as Pkl files under `~/.config/formae/profiles/<name>.pkl`
(honoring `$XDG_CONFIG_HOME` and `$FORMAE_CONFIG_DIR`). The active profile is
recorded in a plain-text `active` file alongside them. Existing setups are
migrated into this layout automatically the first time you run a command that
needs configuration.

## Command reference

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae profile [COMMAND]
```

| Command          | What it does                                                          |
| ---------------- | --------------------------------------------------------------------- |
| `list`           | List all profiles, marking the active one with `*`                    |
| `current`        | Print the active profile name                                         |
| `use <name>`     | Switch the active profile                                             |
| `create <name>`  | Create a new profile from a minimal template (`--force` to overwrite) |
| `save <name>`    | Snapshot the active profile under a new name (`--force` to overwrite) |
| `edit [<name>]`  | Open a profile in `$EDITOR` (the active one if no name)               |
| `delete <name>`  | Delete a profile (refuses the active one)                             |
| `diff <a> [<b>]` | Compare two profiles, or one against the active                       |

`list` and `current` accept `--output-consumer machine` (with
`--output-schema json|yaml`) for scripting.

## See also

* [Install and run the agent](/documentation/guides/install-agent): the installer writes a profile for your new agent.
* [Configuration](/documentation/reference/configuration): the settings a profile holds.