profile command

Manage named formae 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 switch the CLI between environments (local-dev, staging, prod, …) without hand-editing or swapping config files.

Usage

formae profile [COMMAND]

Commands

Command	Description
list	List all profiles, marking the active one with *
current	Print the active profile name
use	Switch the active profile
save	Snapshot the active profile under a new name
create	Create a new profile from a minimal template
edit	Open a profile in $EDITOR
delete	Delete a profile
diff	Compare two profiles

The active profile and --profile

One profile is active at a time, and it applies to every command that connects to the agent (apply, destroy, status, inventory, …). Switch it with formae profile use <name>.

To target a different environment for a single invocation without changing the active selection, pass --profile <name> on any agent-connecting command (plus cancel):

formae apply --profile staging ./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 your formae config directory — ~/.config/formae/profiles/<name>.pkl by default (honors $XDG_CONFIG_HOME and $FORMAE_CONFIG_DIR). The active profile is recorded in a plain-text active file alongside them.

The first time you run a command that needs configuration, any existing setup is migrated into this layout automatically, and a fresh install starts with a ready-to-use default profile pointed at a local agent.

list

List all profiles. The active profile is marked with *.

Usage

formae profile list [--output-consumer human|machine] [--output-schema json|yaml]

Output is human-readable by default. For scripting, --output-consumer machine emits the profile list and the active profile as JSON (or YAML with --output-schema yaml).

current

Print the name of the active profile. On a fresh machine with no active profile yet, it prints no active profile yet. Supports --output-consumer machine for scripting.

Usage

formae profile current [--output-consumer human|machine] [--output-schema json|yaml]

use

Switch the active profile. Errors if the named profile does not exist.

Usage

formae profile use <name>

save

Snapshot the active profile under a new name. Does not change the active profile. Pass --force to overwrite an existing profile of the same name.

Usage

formae profile save <name> [--force]

create

Create a new profile from a minimal starter template. Does not change the active profile. Pass --force to overwrite.

Usage

formae profile create <name> [--force]

edit

Open a profile in $EDITOR. With no argument, edits the active profile.

Usage

formae profile edit [<name>]

delete

Delete a profile. Refuses to delete the active profile — switch to another first.

Usage

formae profile delete <name>

diff

Show a unified diff between two profiles, or between one profile and the active profile.

Usage

formae profile diff <a> [<b>]