Contexts

Overview

Contexts represent different environments (dev, prod, staging) with variable overrides. One context is active at a time.

Configuration

contexts:
    dev:
        description: Local development
        variables:
            constants:
                appEnv: dev
                debug: true

    prod:
        description: Production settings
        variables:
            constants:
                appEnv: prod
                debug: false

defaults:
    context: dev

Switching Contexts

sputnik context:switch prod
# or shorthand:
sputnik switch prod
sputnik use prod

What Happens on Switch

1. ContextSwitchedEvent is dispatched
2. Built-in listener SwitchContextOnServices (priority 100) updates VariableResolver and TemplateEngine
3. Built-in listener RegenerateTemplatesOnContextSwitch (priority 0) re-renders all templates
4. Custom listeners run (use negative priority to run after templates)
5. The context is persisted to .sputnik/state.json

The switch is written down last

Switching a context means preparing the project for it -- regenerating templates, reinstalling dependencies. If a listener fails, the switch is not persisted: the previous context stays active and the command exits non-zero, so you can fix the cause and try again.

Listeners do not need the persisted value to know where they are. They read the new context from the event, and SwitchContextOnServices puts the resolver and the template engine on it before any other listener runs.

Listing Contexts

sputnik context:list
# or:
sputnik contexts

Shows all contexts with descriptions. Current context marked with *.

Variable Overrides

Context constants override global constants:

variables:
    constants:
        appEnv: dev       # default

contexts:
    prod:
        variables:
            constants:
                appEnv: prod  # overrides when prod is active

Only constants can be overridden per context. A dynamics or secrets block under contexts.*.variables is a configuration error, not a silent no-op -- dynamics are evaluated once for the run, and a context-level secret could declassify a global one by shadowing its name.

One-Shot Override

Use --context to override the context for a single command without persisting:

sputnik --context prod deploy

Info

The --context flag does not change the persisted context. After the command finishes, templates are re-rendered with the previously active context.

State Persistence

Active context is stored in .sputnik/state.json. This file is auto-created and should be gitignored (it's inside .sputnik/ directory).

Built-in Variable

The current context name is available as the built-in variable context:

ENVIRONMENT={{ context }}