Switch and Customize Profiles

A profile is the set of extensions kli installs at boot: which model providers load, whether the terminal UI comes up, which tools are present. kli ships these builtins:

• interactive-terminal — the default. Boots the terminal UI with all the model providers and the full tool set.
• headless — the baseline kernel and tools with no terminal UI and no provider extensions. Holds the process open for a programmatic driver.
• human-in-loop — the interactive profile, declaring an approval seam for an extension you supply.
• autonomous — providers and tools without the terminal UI, declaring planner, scheduler, watchdog, and recovery seams.

This guide shows how to choose one at startup, switch while kli runs, and define your own.

Choose a profile at startup

Name a profile on the command line:

kli --profile headless

Or set it in the environment, which kli reads when --profile is absent:

export KLI_PROFILE=headless
kli

To make the choice stick without a flag or env var, set the profile key in settings.json:

{
  "profile": "headless"
}

kli resolves the boot profile in this order, taking the first that names one:

1. --profile <name>
2. KLI_PROFILE
3. the profile key in settings.json
4. the default, interactive-terminal

Set it in settings.json (global ~/.config/kli/settings.json, project <repo>/.kli/settings.json; project wins) — see Settings.

A name that resolves to nothing warns and boots the default profile instead. The warning lands in the transcript as a boot diagnostic.

Switch profiles while kli runs

Run /profile with no argument to list every profile, builtins first, then the ones you defined. The active one carries a *:

Profiles:
* interactive-terminal
  headless
  human-in-loop
  autonomous
  review

Pass a name to switch:

/profile review

A live switch re-bases your own extensions onto the target profile: kli installs the ones the target enables that are not yet present, and retracts the ones present that the target disables. The reply names what changed:

Switched to review. Installed: my-linter.

The delta is computed against what is actually installed, so any manual /enable and /disable you ran since boot re-bases too.

Two switches do not apply:

• Naming the active profile reports that it is already active and changes nothing.
• A profile whose builtin base differs from the running one cannot apply live, because the base set installs only at boot. The builtins each have a distinct base, so a live switch between them always lands here. kli tells you to restart, for example Restart with --profile autonomous.

Define your own profile

Add a profiles block to settings.json. Each key is a profile name; each value describes how it differs from a builtin:

{
  "profiles": {
    "review": {
      "extends": "interactive-terminal",
      "enable": ["my-linter"],
      "disable": ["scratch-notes"],
      "settings": {
        "defaultProvider": "anthropic",
        "defaultModel": "claude-opus-4-6"
      }
    }
  }
}

The fields:

• extends — the profile this one builds on, a builtin or another profile you defined. Omit it and the profile builds on interactive-terminal. The chain must bottom out at a builtin; a cycle or a dangling target is reported and the profile is skipped.
• enable — ids of your own extensions to install that the base would leave out.
• disable — ids of your own extensions to keep out that the base would install. Within one profile disable wins over enable for the same id. enable and disable gate the extensions kli discovers in ~/.config/kli/extensions/ and <repo>/.kli/extensions/, not the builtin tools.
• settings — a settings object that overlays the merged files while this profile is active. Use it to bind a profile to a default provider and model, a set of capabilities, or any other setting.

A profile may not reuse a builtin name (interactive-terminal, headless, human-in-loop, autonomous). kli warns and ignores any entry that does.

Once defined, a profile is selectable everywhere a builtin is: --profile review, KLI_PROFILE=review, the profile key, and /profile review. It also appears in the /profile list and in /profile tab completion.

For how enable and disable sit against the per-extension /enable and /disable commands, see Restrict What kli Can Do and the settings reference. For what an extension is and why retracting one mid-session is safe, see The Live Image.