Configuration & Environment Variables

#Precedence

Peekaboo resolves settings in this order (highest → lowest):

1. Command-line arguments
2. Environment variables (never copied into files)
3. Credentials file (~/.peekaboo/credentials: API keys or OAuth tokens)
4. Configuration file (~/.peekaboo/config.json)
5. Built-in defaults

#Available Options

#API Key Storage

1. Environment variables – supported for existing automation, but keep values out of command arguments.
2. Credentials file – peekaboo config credential set OPENAI_API_KEY prompts without echo and stores the value in ~/.peekaboo/credentials (chmod 600). Scripts should pipe one line with --credential-stdin --no-input or use an owner-only --credential-file.
3. Config file – avoid storing keys here unless absolutely necessary. OAuth tokens are never written to config.json.

The macOS app and CLI use this same file as the ongoing authority for saved API keys, including when PEEKABOO_CONFIG_DIR changes the configuration root. Settings reloads it when the provider pane opens; use Reload keys after a CLI rotation while the pane stays open. There is no credential-path Keychain storage or importer and no password or biometric prompt for app credential persistence.

The directory is owner-only (0700) and the file is owner-readable/writable (0600), including temporary files before publication. This deliberately accepts file-level protection to avoid authentication prompts: the keys are plaintext, and other processes running as your user can read them. Do not share this file. Sequential app/CLI edits preserve unrelated keys and OAuth entries; concurrent edits by separate processes, including Tachikoma, are not serialized.

Old app preferences are never imported automatically, even if the file is missing, empty, or deleted. Import saved app keys explicitly recovers legacy-only keys; existing file values win, including CLI changes made since the pane opened. Successful saves, clears, and imports retire only the corresponding legacy entries. Failed imports leave those entries available for another explicit attempt. Showing a credential field or receiving an unchanged binding value never saves the draft or retires legacy keys. App edits and legacy imports trim surrounding whitespace and newlines; interior newlines and NUL remain invalid. Whitespace-only app input clears a populated field but leaves an already empty field unchanged; blank legacy entries remain stored without offering recovery.

A failed save keeps the draft marked Not saved and leaves the previous effective credential unchanged. A failed clear does not claim deletion or environment fallback. Retry is explicit after failure, and reload preserves failed drafts. A durability warning means publication already happened; reload to check instead of blindly repeating the write. Environment overrides, config fallbacks, OAuth sessions, and the international MiniMax fallback for MiniMax China remain runtime-only and are not implicitly saved.

#Provider Variables

• PEEKABOO_AI_PROVIDERS: provider/model CSV. Example: openai/gpt-5.6,anthropic/claude-opus-5,grok/grok-4.3,ollama/llava:latest.
• OPENAI_API_KEY, ANTHROPIC_API_KEY, GROK_API_KEY | X_AI_API_KEY | XAI_API_KEY, GEMINI_API_KEY, MINIMAX_API_KEY, MINIMAX_CN_API_KEY, MOONSHOT_API_KEY | KIMI_API_KEY: required for their respective providers when using API keys.
• Ollama native endpoint precedence: PEEKABOO_OLLAMA_BASE_URL > OLLAMA_BASE_URL >

aiProviders.ollamaBaseUrl > http://localhost:11434. Set the server base without /api/chat or /v1; see the Ollama provider guide.

#Defaults & Paths

• PEEKABOO_DEFAULT_SAVE_PATH: screenshot destination (created automatically).
• PEEKABOO_CLI_PATH: point Peekaboo at a debug build (.build/debug/peekaboo) without copying binaries around.

#Agent generation settings

The macOS Settings UI and peekaboo agent share agent.temperature and agent.maxTokens through ~/.peekaboo/config.json:

{
  "agent": {
    "defaultModel": "anthropic/claude-fable-5",
    "temperature": 0.7,
    "maxTokens": 128000
  }
}

maxTokens is an upper request, not a promise: Peekaboo clamps it to the selected model's advertised output limit. Fable 5 supports up to 128K output and a 1M context window. Anthropic-compatible custom providers inherit known Fable limits from the model ID, while custom model entries can advertise their own maxTokens.

Temperature is clamped to 0...1 for Anthropic-compatible models and 0...2 elsewhere. Peekaboo omits it entirely for models that reject sampling controls, including GPT-5-compatible endpoints and current Anthropic adaptive-thinking models.

#UI Input Strategy

Input strategy controls whether UI interactions use accessibility action invocation or synthetic input. The built-in policy keeps the global default at synthFirst, flips click and scroll to actionFirst, keeps type and hotkey at synthFirst, and exposes setValue/performAction as action-only operations.

Precedence is --input-strategy CLI flag, then environment, then config file, then built-in default. The CLI flag forces local execution because the current bridge protocol does not forward per-call strategy overrides.

Valid values:

• actionFirst: try accessibility action invocation, fall back to synthetic input when unsupported.
• synthFirst: use synthetic input first.
• actionOnly: use action invocation only.
• synthOnly: use synthetic input only.

Config example:

{
  "input": {
    "defaultStrategy": "synthFirst",
    "click": "actionFirst",
    "scroll": "actionFirst",
    "type": "synthFirst",
    "hotkey": "synthFirst",
    "setValue": "actionOnly",
    "performAction": "actionOnly",
    "perApp": {
      "com.googlecode.iterm2": {
        "hotkey": "synthOnly"
      }
    }
  }
}

Environment variables:

• PEEKABOO_INPUT_STRATEGY
• PEEKABOO_CLICK_INPUT_STRATEGY
• PEEKABOO_SCROLL_INPUT_STRATEGY
• PEEKABOO_TYPE_INPUT_STRATEGY
• PEEKABOO_HOTKEY_INPUT_STRATEGY
• PEEKABOO_SET_VALUE_INPUT_STRATEGY
• PEEKABOO_PERFORM_ACTION_INPUT_STRATEGY

CLI override:

peekaboo click --on "$ELEMENT_ID" --input-strategy actionFirst

#Logging & Troubleshooting

• PEEKABOO_LOG_LEVEL=debug (or trace) surfaces verbose input-path logs.
• PEEKABOO_LOG_FILE=/tmp/peekaboo.log persists logs for sharing.
• Tool filters: env PEEKABOO_ALLOW_TOOLS replaces config tools.allow; env PEEKABOO_DISABLE_TOOLS is additive with tools.deny. Deny wins if a tool appears in both. See docs/security.md for examples and risk guidance.

#Setting Variables

# Single command
PEEKABOO_AI_PROVIDERS="ollama/llava:latest" peekaboo see --analyze "Describe this UI" --path img.png

# Session exports
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export X_AI_API_KEY="xai-..."

# Shell profile
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc

When in doubt, run peekaboo config show --effective to see the merged view from every layer.