/penguin-config

name: penguin-config
description: Manage model API keys, default models and per-agent vault secrets with the penguin CLI.
version: 2026.11.02.1

Penguin Config (CLI)

The `penguin` CLI manages model credentials, default models and per-agent vault secrets. Its primary job is model configuration: `penguin config model add` registers a model, or — without `--model-id` — gives a whole group its key, base URL or protocol, and `penguin config model list` shows the groups' connections and the models currently available. Configuration goes through the CLI only — never read or hand-edit the underlying hidden files.

Before you start

If the user's message only invokes this skill (e.g. "use penguin-cli skill") without a concrete request, ask the user what they want to configure. Do not run any command until the goal is clear.

Models

Add or update a model (upsert by the `(provider, model_id)` pair; re-run with more options to amend an entry):

penguin config model add --provider <group> --model-id <upstream_id> [--api-key <key> | --clear-api-key] \
  [--base-url <url> | --clear-base-url] [--client-type <type> | --clear-client-type] \
  [--context-window <n>] [--max-tokens <n>] [--vision | --no-vision] [--fast-mode | --no-fast-mode] \
  [--price-cache-read <n>] [--price-cache-write <n>] [--price-output <n>] \
  [--project-id <id>] [--root <dir>] [--set-default]

• A model is identified by the `(provider, model_id)` pair, so `--provider` and `--model-id` are **both required** to name one — the group is never inferred from the model id, because gateways resell vendor models under their upstream ids and a wrong guess would send the key to another vendor's endpoint. `--model-id` takes the provider's upstream model id (what the API expects) and is persisted as the entry's request id, so it reaches the API unchanged; `--provider` names the group (`deepseek`, `openai`, `anthropic`, `google`, `openrouter`, `siliconflow`, … — `custom` for any other endpoint).
• Only `custom`, `vllm`, `openrouter`, `tokendance`, `siliconflow`, `atlascloud`, `runcrate` and groups of your own take models added by hand. Every other built-in group carries its catalog models only: `model add` there accepts one of that group's catalog model ids (to set its key, limits or prices, or to bring it back) and refuses any other id with "cannot be added". Add such a model under `custom` with `--base-url`, or under a group of your own.
• `--api-key`, `--base-url` and `--client-type` set the model's **own** values, and `--clear-api-key`, `--clear-base-url` and `--clear-client-type` remove them. Omitted, the model follows its group (see [Group connection](#group-connection)), and with no group value it gets the client's default; the built-in catalog is never consulted. A model added to `openrouter`, `tokendance` or `siliconflow` needs only `--provider` and `--model-id` once the group has a key: a new Project already stores those gateways' endpoint and protocol on the group. For an OpenAI chat-completion compatible endpoint under `custom` or a group of your own, use `--client-type openai --base-url <endpoint>`, or set both once on the group; in a vendor group, omit `--client-type` to auto-route by model id.
• Prices are USD per million tokens (cache read / cache write / output).
• `--vision` / `--no-vision` mark whether the model accepts images; omitting both keeps the current value (default is vision-capable).
• `--max-tokens <n>` pins a per-model output cap (positive integer), overriding the Agent's `model.max_tokens`; omit to inherit. Lower it for small-context models — the per-Agent default (32000) cannot fit into e.g. a 32k context window together with any prompt.
• All `penguin config model ...` and `penguin config vault ...` commands accept `--root <dir>` to target another data root (default `PENGUIN_HOME`, then `~/.penguin/data`). Two configuration targets — treat the difference as a hard rule:
• **Penguin's own model** (self-configuration: the model Penguin itself runs on): pass `--root <data root>` as well — the parent directory of the App Data Dir named in your Environment section. An agent running inside PenguinHarness never sees `PENGUIN_HOME`: the harness strips every `PENGUIN_*` variable from a command's environment, so a command without `--root` falls back to `~/.penguin/data` and configures a root the running server does not read.
• **An AI app you are building**: `--root` **must** point at the app's own data directory inside the project (e.g. `--root ./penguin_data`, the same path the app gives `createAgent({ root })`) unless the user explicitly chose another location — never write an app's models or keys into the global `~/.penguin/data`, which belongs to the person running Penguin, not to the app.
• While developing an app, review regularly: `penguin config model list --root <app root>` should show the app's entries, and the global list (no `--root`) should stay clean.

Other model commands:

penguin config model default --model-id <upstream_id> --provider <group> [--root <dir>]   # set the project default model
penguin config model vision --model-id <upstream_id> --provider <group> [--root <dir>]    # set the project vision model (reads images for text-only sessions)
penguin config model list [--root <dir>]                      # the groups' connections, then the models with the connection each uses; api_key masked, (provider) = from the group, (env) = from an environment variable
penguin config model remove --model-id <upstream_id> --provider <group> [--root <dir>]   # remove one model

Group connection

A group holds one connection — API key, base URL, protocol — in its `[providers.<group>]` table, and every model in it without a value of its own follows it. Each field resolves on its own from the config file alone: the model's value, else the group's, else nothing (the client's default endpoint, MMSP routing by model id, the environment key where allowed). The built-in