cli-config

name	cli-config
description	Guide for configuring Paintress CLI. Use this skill when users want to configure models, tools, subagents, custom commands, or other CLI settings. Covers both global and project-level configuration.

Paintress CLI Configuration

Configuration is loaded from multiple locations with project-level priority (no merging between levels).

Configuration Locations

Level	Location	Priority
Global	~/.config/youware-labs/paintress-cli/	Default
Project	.paintress/	Overrides global

Configuration Files

config.toml (Global)

Main configuration file for model, display, browser, and subagents.

[general]
# Model configuration (required)
# Format: "provider:model_name"
model = "anthropic:claude-sonnet-4-5"

# Model settings preset or custom dict
# Presets: anthropic_default, openai_default, google_default
model_settings = "anthropic_default"

# Model config for context management
# Presets: claude_200k, claude_1m, gpt5_270k, gemini_1m
model_cfg = "claude_200k"

# Maximum requests per session
max_requests = 1000

[env]
# Environment variable overrides for API keys
# ANTHROPIC_API_KEY = "sk-ant-..."

[display]
code_theme = "dark"           # "dark" or "light"
max_tool_result_lines = 5
max_arg_length = 100
show_token_usage = true
show_elapsed_time = true

[browser]
# cdp_url = "auto"            # null, "auto", or explicit URL
browser_image = "zenika/alpine-chrome:latest"
browser_timeout = 30

[subagents]
disabled = []                 # Subagents to disable by name
# [subagents.overrides.explorer]
# model = "openai:gpt-4o"

tools.toml (Project)

Project-level tool permissions in .paintress/tools.toml:

[tools]
# Tools requiring user approval before execution
need_approval = ["shell", "replace"]

Common patterns:

• [] - No approval needed (trust all tools)
• ["shell"] - Approve shell commands only
• ["shell", "replace", "edit"] - Approve all code modifications

mcp.json

MCP server configurations:

{
  "servers": {
    "my-server": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@some/mcp-server"],
      "env": {}
    }
  }
}

Custom Slash Commands

Define custom commands in config.toml:

[commands.deploy]
description = "Deploy to production"
mode = "act"                  # Optional: "act" or "plan"
prompt = """
Please help me deploy to production...
"""

Built-in commands: /init, /commit, /review

Subagent Configuration

Create markdown files in ~/.config/youware-labs/paintress-cli/subagents/:

---
name: my-subagent
description: Brief description shown when selecting tools
instruction: |
  When to use this subagent and what to provide
tools:
  - grep
  - view
optional_tools:
  - shell
model: inherit
---

You are a specialist in [domain].

## Process
1. Step one
2. Step two

Configuration Fields

Field	Required	Description
name	Yes	Unique identifier, becomes the tool name
description	Yes	Shown to model when selecting tools
instruction	No	Injected into parent's system prompt
tools	No	Required tools - ALL must be available
optional_tools	No	Optional tools - included if available
model	No	"inherit" or model name

Tool Availability Rules

• Required tools (tools): Subagent disabled if ANY unavailable
• Optional tools (optional_tools): Included only if available
• No tools specified: Inherits all parent tools

Builtin Presets

Preset	Purpose	Required Tools
debugger	Root cause analysis	glob, grep, view, ls
explorer	Codebase navigation	glob, grep, view, ls
code-reviewer	Code quality review	glob, grep, view, ls
searcher	Web research	search

Skills Directory

Skills are loaded from (highest priority last):

1. Built-in: paintress_cli/skills/ (package bundled)
2. Global: ~/.config/youware-labs/paintress-cli/skills/
3. Project: .paintress/skills/

Environment Variables

TUI settings can be overridden via PAINTRESS_* environment variables:

• PAINTRESS_CODE_THEME
• PAINTRESS_SHOW_TOKEN_USAGE
• PAINTRESS_CDP_URL
• PAINTRESS_SESSION_DIR

Quick Setup

Run paintress setup to initialize global configuration with defaults.