create/update profile

rsspot resolves settings from runtime input, config files, environment variables, and sqlite-backed preferences.

Config File Locations and Migration

Canonical config search path:

~/.config/rsspot/config.yml
~/.config/rsspot/config.yaml
~/.config/rsspot/config.toml
~/.config/rsspot/config.json

Legacy fallback:

~/.spot_config

When only legacy config exists, rsspot loads it, normalizes it, and persists migrated config to the canonical path.

Supported Formats

YAML (.yml, .yaml)
TOML (.toml)
JSON (.json)

Writes use the extension of the selected target path and set file mode 0600.

Resolution Precedence

For SpotClient / AsyncSpotClient:

Runtime config dict/model passed to constructor (config=)
Explicit config_path=
Env config path:
- RSSPOT_CONFIG
- RSSPOT_CONFIG_FILE
- SPOT_CONFIG_FILE
Canonical default path search (~/.config/rsspot/...)
Legacy ~/.spot_config migration fallback

Within selected config/profile, effective runtime values resolve as:

Explicit constructor args
Runtime env aliases (RSSPOT_*, SPOT_*, RACKSPACE_* where supported)
sqlite preferences (default_profile, default_org, default_region)
Config profile fields and config-level preferences
SDK defaults

Config Model (v2)

The expected schema is the same for config.yaml, config.toml, and config.json.

`config.yaml`

version: "2"
default_profile: prod
active_profile: prod
state_path: /Users/you/.config/rsspot/state.db

profiles:
  prod:
    org: sparkai
    region: us-central-dfw-1
    refresh_token: replace-me
    base_url: https://spot.rackspace.com
    oauth_url: https://spot.rackspace.com
    request_timeout_seconds: 30
    verify_ssl: true
    retry:
      max_attempts: 4
      base_delay: 0.2
      max_delay: 2.5
      jitter: 0.2
      retry_statuses: [429, 500, 502, 503, 504]
    cache:
      enabled: true
      default_ttl: 5
      max_entries: 1000
      backend: sqlite
      ttl_defaults:
        GET:/apis/auth.ngpc.rxt.io/v1/organizations: 10
        GET:/apis/ngpc.rxt.io/v1/regions: 20

preferences:
  default_profile: prod
  default_org: sparkai
  default_region: us-central-dfw-1
  profile_orgs:
    prod: sparkai
  profile_regions:
    prod: us-central-dfw-1

retry:
  max_attempts: 4
  base_delay: 0.2
  max_delay: 2.5
  jitter: 0.2

cache:
  enabled: true
  default_ttl: 5
  max_entries: 1000
  backend: sqlite

`config.toml`

version = "2"
default_profile = "prod"
active_profile = "prod"
state_path = "/Users/you/.config/rsspot/state.db"

[profiles.prod]
org = "sparkai"
region = "us-central-dfw-1"
refresh_token = "replace-me"
base_url = "https://spot.rackspace.com"
oauth_url = "https://spot.rackspace.com"
request_timeout_seconds = 30
verify_ssl = true

[profiles.prod.retry]
max_attempts = 4
base_delay = 0.2
max_delay = 2.5
jitter = 0.2
retry_statuses = [429, 500, 502, 503, 504]

[profiles.prod.cache]
enabled = true
default_ttl = 5
max_entries = 1000
backend = "sqlite"

[profiles.prod.cache.ttl_defaults]
"GET:/apis/auth.ngpc.rxt.io/v1/organizations" = 10
"GET:/apis/ngpc.rxt.io/v1/regions" = 20

[preferences]
default_profile = "prod"
default_org = "sparkai"
default_region = "us-central-dfw-1"

[preferences.profile_orgs]
prod = "sparkai"

[preferences.profile_regions]
prod = "us-central-dfw-1"

[retry]
max_attempts = 4
base_delay = 0.2
max_delay = 2.5
jitter = 0.2

[cache]
enabled = true
default_ttl = 5
max_entries = 1000
backend = "sqlite"

`config.json`

{
  "version": "2",
  "default_profile": "prod",
  "active_profile": "prod",
  "state_path": "/Users/you/.config/rsspot/state.db",
  "profiles": {
    "prod": {
      "org": "sparkai",
      "region": "us-central-dfw-1",
      "refresh_token": "replace-me",
      "base_url": "https://spot.rackspace.com",
      "oauth_url": "https://spot.rackspace.com",
      "request_timeout_seconds": 30,
      "verify_ssl": true,
      "retry": {
        "max_attempts": 4,
        "base_delay": 0.2,
        "max_delay": 2.5,
        "jitter": 0.2,
        "retry_statuses": [429, 500, 502, 503, 504]
      },
      "cache": {
        "enabled": true,
        "default_ttl": 5,
        "max_entries": 1000,
        "backend": "sqlite",
        "ttl_defaults": {
          "GET:/apis/auth.ngpc.rxt.io/v1/organizations": 10,
          "GET:/apis/ngpc.rxt.io/v1/regions": 20
        }
      }
    }
  },
  "preferences": {
    "default_profile": "prod",
    "default_org": "sparkai",
    "default_region": "us-central-dfw-1",
    "profile_orgs": {
      "prod": "sparkai"
    },
    "profile_regions": {
      "prod": "us-central-dfw-1"
    }
  },
  "retry": {
    "max_attempts": 4,
    "base_delay": 0.2,
    "max_delay": 2.5,
    "jitter": 0.2
  },
  "cache": {
    "enabled": true,
    "default_ttl": 5,
    "max_entries": 1000,
    "backend": "sqlite"
  }
}

Notes:

profiles.<name> contains profile-specific values; these are what you usually vary by environment.
Top-level retry and cache apply globally and can be overridden per profile.
Legacy aliases (refreshToken, clientId, baseUrl, etc.) are accepted for compatibility.

Environment Variables

Concern	Accepted env vars
Config file path	`RSSPOT_CONFIG`, `RSSPOT_CONFIG_FILE`, `SPOT_CONFIG_FILE`
Active profile	`RSSPOT_PROFILE`, `SPOT_PROFILE`
Org selector	`RSSPOT_ORG`, `RACKSPACE_ORG`, `SPOT_ORG`
Org id	`RSSPOT_ORG_ID`, `RSSPOT_ORGID`, `RACKSPACE_ORG_ID`, `SPOT_ORG_ID`
Region	`RSSPOT_REGION`, `RACKSPACE_REGION`, `SPOT_REGION`
Refresh token	`RSSPOT_REFRESH_TOKEN`, `RACKSPACE_REFRESH_TOKEN`, `SPOT_REFRESH_TOKEN`
Access token seed	`RSSPOT_ACCESS_TOKEN`, `RACKSPACE_ACCESS_TOKEN`, `SPOT_ACCESS_TOKEN`
Client id	`RSSPOT_CLIENT_ID`, `RACKSPACE_CLIENT_ID`, `RXTSPOT_CLIENT_ID`
API base URL	`RSSPOT_BASE_URL`, `RACKSPACE_BASE_URL`, `SPOT_BASE_URL`
OAuth URL	`RSSPOT_OAUTH_URL`, `RACKSPACE_OAUTH_URL`, `SPOT_AUTH_URL`
Retry tuning (legacy knobs)	`RSSPOT_MAX_RETRIES`, `SPOT_MAX_RETRIES`, `RSSPOT_RETRY_BACKOFF_FACTOR`, `SPOT_RETRY_BACKOFF_FACTOR`

SQLite State

state.db persists:

preference keys (default_profile, default_org, default_region, etc.)
HTTP cache entries
redacted CLI command history
VM registration ledger records

Default path:

Next to resolved config file (<config-dir>/state.db)
Fallback ~/.config/rsspot/state.db when config path is runtime-only

Override with state_path= or config state_path.

Profile Workflows

# create/update profile
uv run rsspot configure --profile prod --org sparkai --region us-central-dfw-1 --refresh-token "$TOKEN"

# inspect profiles
uv run rsspot profiles list
uv run rsspot profiles show prod

# switch active profile
uv run rsspot profiles use prod

# persist default selectors into sqlite state
uv run rsspot config set-default-profile prod
uv run rsspot config set-default-org sparkai
uv run rsspot config set-default-region us-central-dfw-1