Configuration

How to configure skene using config files, environment variables, and CLI flags.

Configuration priority

Settings are loaded in this order (later overrides earlier):

1. User config     ~/.config/skene/config     (lowest priority)
2. Project config  ./.skene.config
3. Env variables   SKENE_API_KEY, SKENE_PROVIDER, etc.
4. CLI flags       --api-key, --provider, etc.        (highest priority)

Config file locations

Both files use TOML format. The user-level path respects XDG_CONFIG_HOME if set.

Creating a config file

# Create .skene.config in the current directory
uvx skene config --init

This creates a sample config file with restrictive permissions (0600 on Unix).

Interactive editing

Running config without flags opens interactive editing:

uvx skene config

This prompts you for:

1. LLM provider: numbered list: openai, gemini, anthropic, lmstudio, ollama, generic
2. Model: numbered list of provider-specific models, or enter a custom name
3. Base URL: only if generic provider is selected
4. API key: password input (masked), with option to keep existing value

Viewing current config

uvx skene config --show

Displays all current configuration values and their sources.

Config options

Sticky output directory

If output_dir is not set in config and SKENE_OUTPUT_DIR is unset, Skene infers a default of ./skene-context vs ./skene by looking for bundle directories skene-context/ (preferred) and skene/ (legacy) under a project root.

• Which root: Commands that take a project path (for example skene push ./my-repo or skene analyse-journey ./my-repo) resolve this layout against that directory, not necessarily your shell's current working directory. That way a different cwd cannot pick the wrong bundle.
• Precedence: If both skene-context/ and skene/ exist under that root, skene-context wins. If only skene/ exists, sticky defaults to ./skene.
• Override: Set output_dir in .skene.config or SKENE_OUTPUT_DIR to skip sticky detection entirely.

Default models by provider

Sample config file

# .skene.config

# API key (can also use SKENE_API_KEY env var)
# api_key = "your-api-key"

# LLM provider: openai, gemini, anthropic, claude, lmstudio, ollama, generic
provider = "openai"

# Model (defaults per provider if not set)
# model = "gpt-4o"

# Base URL for OpenAI-compatible endpoints (required for generic provider)
# base_url = "https://your-api.com/v1"

# Default output directory
output_dir = "./skene-context"

# Enable debug mode (shows diagnostic messages and logs LLM I/O to ~/.local/state/skene/debug/)
debug = false

# Folders to exclude from analysis
# Matches by: exact name, substring in folder names, path patterns
exclude_folders = ["tests", "vendor"]

Environment variables

Server settings

skene attach <url> connects the CLI to a running skene serve instance: it verifies the server's /health and saves server_url / server_token to .skene.config (the project config if one exists, otherwise the user config). Once attached, analyse-journey runs on that server. skene attach --clear removes the settings.

Session database

Every analyse-journey run (embedded or served) persists a session trace in a global SQLite database at ~/.local/share/skene/skene.db. Override the location with SKENE_DB_PATH or skene serve --db-path. The database holds sessions for every workspace on the machine; nothing is deleted automatically.

Upstream credentials

When using skene push to deploy to Skene Cloud, upstream URL, workspace slug, and API key are stored in .skene.config (with 0600 permissions). These fields are managed by skene login and skene logout. See the login guide for details.

Excluding folders

Custom exclusions from the config file are merged with the built-in defaults.

Default exclusions

The following directories are always excluded: node_modules, .git, __pycache__, .venv, venv, dist, build, .next, .nuxt, coverage, .cache, .idea, .vscode, .svn, .hg, .pytest_cache.

How matching works

Exclusion matches in three ways:

1. Exact name: "tests" matches a folder named exactly tests
2. Substring: "test" matches tests, test_utils, integration_tests
3. Path pattern: "tests/unit" matches any path containing that pattern

Examples

# In .skene.config
exclude_folders = ["tests", "vendor", "migrations", "docs"]

Next steps

• LLM providers: Detailed setup for each provider
• CLI reference: All commands and flags