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 and penguin config model list shows 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>] [--base-url <url>] \
  [--client-type <type>] [--context-window <n>] [--max-tokens <n>] [--vision | --no-vision] \
  [--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 — 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).
• For any OpenAI chat-completion compatible endpoint use --client-type openai --base-url <endpoint>; 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): the default root without --root is correct.
  • 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.