Penguin Config

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 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), 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