Config config

Overview

The config topic sets, shows and removes per-user default values for command options. Set a default once at a topic, group or action level and every command at or below that level uses it unless you pass the option on the command line.

The command tree of config mirrors every other topic, group and action. An option that a command accepts is configurable under the same path and with the same name, except the options listed in What can't be configured. The topic, group and action words select the level you are configuring.

Usage

Set a topic-wide default

This sets --model for every llm action that has a --model option:

Set llm --model = claude-sonnet-5-5

Override it for one action

A default set on an action wins over the default set on its topic, so chat uses gpt-6-luna while the other llm actions keep claude-sonnet-5-5:

Set llm chat --model = gpt-6-luna

Show the effective values

Run a level with no options to list the values it resolves to. Each line names the level the value comes from.

--model = gpt-6-luna (from: llm chat)

--model = claude-sonnet-5-5 (from: llm)

A level with nothing configured prints No configured defaults for <level>.

Remove a default

--unset removes the value stored at that level only. The levels above it are not affected. It is repeatable, and the leading dashes on the name are optional:

Unset llm chat --model

After that, pbtk config llm chat falls back to the topic-level value:

--model = claude-sonnet-5-5 (from: llm)

Removing a name that is not set at that level prints llm chat --model was not set and exits 0. A name that is not configurable at that level is an error (see What can't be configured).

Help shows the configured defaults

Once a default is set, the action's --help shows it as [default: …], so you can see the value the command will use before running it:

Description:
  Chat with an LLM maintaining conversation history

Usage:
  Pixelbadger.Toolkit llm chat [options]

Options:
  --message <message> (REQUIRED)         The message to send to the LLM
  --session-id <session-id>              Session ID to continue a previous conversation (omit to start a new session)
  --model <model>                        The model to use (defaults to the provider's default model) [default: gpt-6-luna]
  --provider <claude|openai>             The LLM provider to use (supported: openai, claude) [default: openai]
  --reasoning-effort <reasoning-effort>  Reasoning effort level (supported values depend on --provider)
  -?, -h, --help                         Show help and usage information

Validation

Values are parsed and checked by the same option definitions the real command uses. For example, --provider accepts only openai and claude:

Error: Argument 'nope' not recognized. Must be one of:
	'openai'
	'claude'

On an error, the command exits with status 1 and nothing is written. When one command sets several values and one of them is invalid, none of them are stored.

Error: Invalid reasoning effort 'ultra' for provider 'openai'. Supported values:
low, medium, high

Precedence

For each option, the value that is used is the first one found in this order:

1. The value given on the command line.
2. The default configured at the action level (for example llm chat).
3. The default configured at the group level (for example oauth profile).
4. The default configured at the topic level (for example llm).
5. The built-in default of the option.

Each level is checked only at that level's own path. For example, a default set on oauth applies to oauth profile add unless the group or the action sets its own value.

Here is a worked example with a real server. The built-in --port default of web serve-html is 8080:

  --port <port>             Port to bind the server to [default: 9100]

With --port 9100 stored on the action, starting the server without --port binds 9100. Passing --port 9200 on the command line binds 9200 instead. Unsetting the action value makes the topic value, 9000, apply again.

What can't be configured

These cannot be set through config. Passing one to config fails as an unknown argument:

• Required options. For example llm chat --message, web serve-html --file and gpt train --source. A required value is always specific to the run.
• Immutable options. These are marked as never persisted, because they are secrets, destructive or identify a session. They are llm chat --session-id, llm generate-image --overwrite, gpt train --resume and oauth profile add --client-secret (also oauth profile update --client-secret). The mcp topic adds mcp serve --host, mcp serve --port, mcp serve --allow-remote, and every option of mcp save (--name, --include, --host, --port) and mcp delete (--name). mcp serve --profile, by contrast, is configurable.
• The config topic itself. pbtk config config is not a valid command.

Storage

Defaults live in a SQLite database. Its location is:

• $XDG_CONFIG_HOME/pbtk/config.db when XDG_CONFIG_HOME is set, otherwise ~/.config/pbtk/config.db, on Linux and macOS.
• %APPDATA%\pbtk\config.db on Windows.

The database has one table per topic, named after the topic. Each row holds the action path (empty for the topic level, otherwise words such as chat or profile add), the option name, and the value. A topic only reads and writes its own table.

The database is created on the first set. A missing database is treated as having no defaults.

Bad config

If the database cannot be read, every command that reads defaults fails with:

Error: config database <path> is unreadable: <reason>

A stored value that no longer validates fails only the actions that use it, and only when the option falls back to that default. Passing the option on the command line avoids the stored value. For example:

Configured default for web serve-html --port is invalid: Cannot parse argument 'abc' for option '--port' as expected type 'System.Int32'.

An entry that does not match a configurable option at its level is ignored. Each command of that topic prints a warning to stderr for it. The row stays in the database until you unset it:

Warning: ignoring unknown config entry web nope --port

Command Reference