Settings

Configure the strata extension behavior via VS Code settings. Open settings with Ctrl+, (or Cmd+, on Mac) and search for “strata”.

All Settings

Setting	Type	Default	Description
strata.cliPath	string	"strata"	CLI executable or command (e.g., "uv run strata")
strata.validateOnSave	boolean	true	Run validation on file save
strata.validateOnType	boolean	false	Run validation with 1.5s debounce while typing
strata.showCodeLens	boolean	true	Show inline CodeLens actions (Validate, Build, Deploy, Schema, Guide)
strata.showStatusBar	boolean	true	Show status bar item (health, profile, phase)
strata.autoExportSchemas	boolean	false	Auto-export and wire JSON schemas on workspace open
strata.showFileDecorations	boolean	true	Show validation badges (✅/⚠️/❌) in file tree
strata.defaultProfile	string	""	Profile to activate automatically on workspace open (empty = last active)

Details

strata.cliPath

Type: string
Default: "strata"
Description: Path to the strata CLI executable.

Examples:

"strata.cliPath": "strata"           // CLI in $PATH
"strata.cliPath": "/usr/local/bin/strata"  // Full path
"strata.cliPath": "uv run strata"    // Via uv
"strata.cliPath": "poetry run strata"// Via poetry
"strata.cliPath": "C:\\tools\\strata.exe"  // Windows

How it’s used:

The extension runs:

<cliPath> [arguments]

So "strata.cliPath": "uv run strata" becomes:

uv run strata validate <file>

Finding your CLI:

In a terminal, run:

which strata          # macOS/Linux
where strata          # Windows

If not in $PATH, install it first:

pip install strata
# or
pip install --user strata

Then check where it was installed:

pip show strata       # shows Location field

strata.validateOnSave

Type: boolean
Default: true
Description: Automatically validate files on save.

• When true — every time you save a .yaml file, validation runs

• When false — validation only runs on-demand (Command Palette, CodeLens, right-click)

Use case:

• Enable (true) for tight feedback loops (errors caught immediately)

• Disable (false) if validation is slow or you prefer manual control

strata.validateOnType

Type: boolean
Default: false
Description: Validate while typing with a 1.5-second debounce.

• When true — 1.5 seconds after you stop typing, validation runs

• When false — only on save or on-demand

Debounce: 1.5 seconds of inactivity before validation starts. This prevents excessive CLI calls while you’re typing.

Use case:

• Enable (true) if you have a fast machine and want live feedback

• Disable (false) on slow hardware or large workspaces to avoid slowdowns

Warning: Enabling both validateOnSave and validateOnType means validation can run frequently. Be aware of CPU/disk impact.

strata.showCodeLens

Type: boolean
Default: true
Description: Show inline CodeLens actions above YAML documents.

When true, you see:

# [Validate] [Schema] [Build DryRun] [Deploy DryRun] [Guide]
apiVersion: strata.huybrechts.xyz/v1

When false, these lenses are hidden.

Note: Even when hidden, the actions still work via Command Palette or right-click menu.

strata.showStatusBar

Type: boolean
Default: true
Description: Show status bar item in the bottom-left corner.

When true:

$(cloud) strata: dev | Phase 5/8

When false, the status bar item is hidden (but workspace health is still tracked internally).

strata.autoExportSchemas

Type: boolean
Default: false
Description: Automatically export and wire JSON schemas on workspace open.

When true:

1. On extension activation, runs strata schema export

2. Generates JSON schemas to .strata/schemas/

3. Runs strata schema wire to update .vscode/settings.json with yaml.schemas mapping

4. The YAML extension (if installed) immediately provides autocomplete and validation

Use case:

• Enable if you want one-time automatic schema setup

• After enabling, restart VS Code or reload window

Manual alternative:

If you keep this false, you can manually export + wire via:

Command Palette → "Strata: Export Schemas"

strata.showFileDecorations

Type: boolean
Default: true
Description: Show validation status badges in the file tree.

When true, files are decorated:

✓  config/main.yaml         ← validated, no issues
⚠️  config/test.yaml        ← warnings
❌ deploy/prd.yaml         ← errors

When false, badges are hidden (but validation still runs).

Performance: Decorations are lightweight and don’t impact performance.

strata.defaultProfile

Type: string
Default: "" (empty)
Description: Profile to activate automatically on workspace open.

Examples:

"strata.defaultProfile": ""          // Don't auto-activate (use last active)
"strata.defaultProfile": "dev"       // Auto-activate 'dev' profile
"strata.defaultProfile": "production"// Auto-activate 'production' profile

How it works:

When the extension activates:

1. If defaultProfile is non-empty, the extension calls strata profile activate <name>

2. If successful, _refreshAll() runs to update all UI

3. If the profile doesn’t exist, you’ll see an error notification

Use case:

• Set to your development profile so each workspace opens with the right profile already active

• Leave empty to use whatever profile was active last time

Workspace vs User Settings

Settings can be configured at two levels:

User Settings (.config/Code/settings.json)

Apply to all workspaces. Use for global preferences.

Workspace Settings (.vscode/settings.json)

Apply only to the current workspace. Use for project-specific overrides.

Example: per-workspace CLI path

Workspace .vscode/settings.json:

{
  "strata.cliPath": "uv run strata"
}

This overrides the global setting just for this workspace.

Command-Line Configuration

Settings can also be set via VS Code CLI:

code --user-data-dir /tmp/vscode-data \
  --install-extension strata \
  --settings strata.cliPath="uv run strata"

Programmatic Access

In the extension code, settings are read with:

const setting = vscode.workspace
  .getConfiguration('strata')
  .get<string>('cliPath', 'strata');

Changes to settings are picked up immediately (no reload needed) because the extension listens to onDidChangeConfiguration.

Troubleshooting

Settings are not taking effect

1. Check spelling (e.g., strata.validateOnSave not strata.validateonsave)

2. Reload the window: Ctrl+Shift+P → “Developer: Reload Window”

3. Check if workspace settings are overriding user settings

“Unknown configuration setting”

→ You’re using an old version of the extension. Update from the Marketplace.

CLI path is wrong but settings show correct value

→ Might be a shell issue. Try:

# Test if the CLI works
$(which strata) --version
# or
uv run strata --version

If it fails, fix your shell environment first (add to $PATH, install dependencies, etc.).