Configuration

The smplkit SDKs resolve configuration from multiple sources with well-defined precedence. You can configure the SDK entirely through environment variables, a configuration file, constructor arguments, or any combination.

Precedence

Configuration is resolved in this order. Each step overlays only the keys it provides:

1. SDK defaults — built-in fallback values
2. Configuration file (~/.smplkit) — profiles with shared defaults
3. Environment variables (SMPLKIT_*) — override file config
4. Constructor arguments — override everything

A key set at a higher-numbered layer always wins. Keys not set at that layer fall through to the next layer down.

Configuration File

The configuration file at ~/.smplkit uses INI format with named profiles and a [common] section for shared defaults.

# Shared defaults applied to every profile
[common]
api_key = sk_api_abc123
debug = false
disable_telemetry = false

# Default profile — used when no profile is specified
[default]
environment = production
service = my-service

# Local development
[local]
base_domain = localhost
scheme = http
environment = local
service = my-service
debug = true

# Staging
[staging]
environment = staging
service = my-service

Values from [common] are applied first, then the active profile overlays its keys on top.

Configuration Reference

File Key	Env Var	Type	Default	Description
api_key	SMPLKIT_API_KEY	string	(required)	Account-scoped API key
base_domain	SMPLKIT_BASE_DOMAIN	string	smplkit.com	Base domain for API requests
scheme	SMPLKIT_SCHEME	string	https	URL scheme (http for local dev)
environment	SMPLKIT_ENVIRONMENT	string	(required)	Runtime environment key
service	SMPLKIT_SERVICE	string	(required)	Runtime service key
debug	SMPLKIT_DEBUG	bool	false	Enable debug logging
disable_telemetry	SMPLKIT_DISABLE_TELEMETRY	bool	false	Disable metric reporting

Boolean values accept: true, 1, yes (truthy) and false, 0, no (falsy), case-insensitive.

Profiles

The SDK loads the [default] profile unless you specify otherwise. Select a different profile with:

• Environment variable: SMPLKIT_PROFILE=local
• Constructor argument: pass profile to the client constructor

The constructor argument takes precedence over the environment variable.

Profile resolution:

1. Start with [common] values (if the section exists)
2. Overlay the selected profile's values
3. Overlay any SMPLKIT_* environment variables
4. Overlay any constructor arguments

Usage

Auto-resolve (no arguments)

With a config file or environment variables in place, the client resolves everything automatically:

from smplkit import SmplClient

with SmplClient() as client:
    # Resolves api_key, environment, service from
    # ~/.smplkit [default] profile or SMPLKIT_* env vars
    pass

Named profile

Select a profile to load its configuration:

from smplkit import SmplClient

with SmplClient(profile="local") as client:
    # Loads [common] + [local] from ~/.smplkit
    pass

Explicit overrides

Constructor arguments override all other sources:

from smplkit import SmplClient

with SmplClient(
    api_key="sk_api_abc123",
    environment="staging",
    service="my-service",
    profile="staging",
    debug=True,
) as client:
    pass

Precedence Example

Given this config file:

[common]
api_key = sk_api_from_file
debug = false

[default]
environment = production
service = web-app

And this environment variable:

export SMPLKIT_ENVIRONMENT=staging

And this constructor call:

client = SmplClient(debug=True)

The resolved configuration is:

Key	Value	Source
api_key	sk_api_from_file	Config file [common]
environment	staging	Environment variable (overrides file)
service	web-app	Config file [default]
debug	true	Constructor argument (overrides everything)

Tips

Local development — Create a [local] profile that points to your local platform:

[local]
base_domain = localhost
scheme = http
environment = local
service = my-service
debug = true

Then start the client with profile="local" or set SMPLKIT_PROFILE=local.

Shell integration — Use direnv to auto-switch profiles per project. Add to your .envrc:

export SMPLKIT_PROFILE=local

Or create shell aliases:

alias smpl-local='export SMPLKIT_PROFILE=local'
alias smpl-staging='export SMPLKIT_PROFILE=staging'
alias smpl-prod='unset SMPLKIT_PROFILE'  # falls back to [default]

CI/CD — In CI pipelines, skip the config file entirely. Set SMPLKIT_API_KEY, SMPLKIT_ENVIRONMENT, and SMPLKIT_SERVICE as pipeline variables. The SDK resolves them without needing ~/.smplkit.