Formae Config

---
name: formae-config
description: "Use when the user wants to switch, list, save, edit, delete, or compare formae configuration profiles in ~/.config/formae/"
---

# formae-config

formae configuration profiles are named configs under the formae config dir
(`~/.config/formae/profiles/<name>.pkl`), with the active one recorded in a
plain pointer file (`<config-dir>/active`). They are managed by the
`formae profile` subcommand (formae >= 0.87.0) and exposed through the
formae-mcp server as native tools. The old stand-alone `fcfg` binary is gone.

Switching the active profile takes effect for subsequent MCP calls immediately —
no agent or MCP-server restart needed.

## MCP tools

| Intent | Tool | Notes |
|--------|------|-------|
| List profiles + active | `list_profiles` | returns `{"active": "<name>", "profiles": ["..."]}` |
| Show active | `current_profile` | returns `{"active": "<name>"}` |
| Switch active (default env) | `use_profile` | `{ "name": "<name>" }` — global; only on explicit "change my default" requests (see below) |
| Snapshot active under a new name | `save_profile` | `{ "name": "<name>", "force": false }` (does not switch) |
| Create from template | `create_profile` | `{ "name": "<name>", "force": false }` (does not switch) |
| Delete | `delete_profile` | refuses the active profile — switch first |
| Compare | `diff_profiles` | `{ "a": "<name>", "b": "<name>?" }` (b defaults to active) |
| View PKL | `read_profile` | `{ "name": "<name>" }` returns the profile's PKL |
| Replace PKL | `write_profile` | `{ "name": "<name>", "content": "<pkl>" }` |

All profile tools require formae >= 0.87.0; on an older formae they return
`requires formae >= 0.87.0 (connected: A.B.C)`.

## Editing a profile

There is no interactive `$EDITOR` step. To modify a profile:

1. `read_profile` to fetch its current PKL.
2. Edit the PKL.
3. `write_profile` to replace it.

`write_profile` is **overwrite-only** (use `create_profile` for a new profile) and
**refuses the active profile** — to edit the active one, `use_profile` to switch
away first (or `save_profile` a copy, edit the copy, then switch). Content is
written as-is; formae has no config validator, so a malformed profile surfaces at
the next `use_profile`/apply rather than at write time.

## Targeting an environment — prefer `profile`, don't switch active

**Default to the per-invocation `profile` argument; do not switch the active
profile to set up a session.** Every agent-touching tool (apply / destroy /
status / inventory / list_* / force_* / cancel / extract) accepts an optional
`profile` argument that targets that one call only and changes no global state.

This matters because the active profile is **global, persisted state** shared with
the user's `formae` CLI and every other concurrent session. Multiple sessions may
be working against different agents at the same time, so calling `use_profile` to
"point this session at staging" would silently redirect those other sessions too.
Always pass `profile` per call instead.

Only call `use_profile` when the user **explicitly** asks to change their default
environment/agent (e.g. "make prod my default") — never as a per-session setup step.

The plugin-hub tools (`search_hub_plugins`, `get_hub_plugin`,
`list_plugin_examples`, `get_plugin_example`) and `create_inline_policy` do **not**
accept `profile` (they don't talk to a specific agent) — don't pass it to them.

## Direct CLI (when not using the MCP)

- `formae profile list --output-consumer machine --output-schema json`
- `formae profile current --output-consumer machine --output-schema json`
- `formae profile use <name>` / `create <name>` / `save <name> [--force]` /
  `delete <name>` / `diff <a> [<b>]`

## Worked example

User: "switch my formae to load-test"

1. Call `use_profile` with `{ "name": "load-test" }`.
2. On a version error: tell the user they need formae >= 0.87.0.
3. On "profile not found": call `list_profiles` to show what's available.
4. On success: confirm. No restart needed — subsequent tools use load-test.