CLI Preferences and Defaults

Some CLI options apply across many commands — output format, verbosity, quiet mode. Rather than repeating --output json --verbose on every invocation, the CLI supports two mechanisms to set persistent defaults.

Option A: Environment Variables

Set env vars in your shell profile (local dev) or pipeline definition (CI/CD). These are read at startup and used as defaults when the corresponding flag is not explicitly passed.

Env var	Equivalent flag	Example value
`STRATA_OUTPUT`	`--output`	`json`, `text`, `console`
`STRATA_VERBOSE`	`--verbose`	`true`, `1`
`STRATA_QUIET`	`--quiet`	`true`, `1`
`STRATA_WORK_PATH`	`--work-path`	`/path/to/workspace`
`STRATA_NO_COLOR`	`--no-color`	`1`, `true`
`NO_COLOR`	`--no-color`	any value (see below)

NO_COLOR standard: strata respects the cross-tool NO_COLOR convention — setting NO_COLOR to any value (including empty string) disables all ANSI color output from both the CLI and the structured logger. Use STRATA_NO_COLOR for strata-specific control, or NO_COLOR when you want a single env var to silence color across all tools in a pipeline.

Local dev — PowerShell profile ($PROFILE):

$env:STRATA_OUTPUT = "console"
$env:STRATA_WORK_PATH = "C:\Projects\myworkspace"

Local dev — bash/zsh profile (~/.bashrc or ~/.zshrc):

export STRATA_OUTPUT=console
export STRATA_WORK_PATH=/home/user/projects/myworkspace

CI/CD — Azure Pipelines:

- script: strata build
  env:
    STRATA_OUTPUT: json
    STRATA_WORK_PATH: $(Pipeline.Workspace)/myworkspace

CI/CD — GitHub Actions:

- run: strata build
  env:
    STRATA_OUTPUT: json
    STRATA_WORK_PATH: ${{ github.workspace }}/myworkspace

Pros:

Zero workspace dependency — works before strata sln init
Standard pattern — well understood by CI/CD systems
Per-shell overrides are easy (STRATA_OUTPUT=json strata validate for one invocation)

Cons:

Global to the shell — affects all workspaces open in the same session
Must be configured separately per machine / pipeline

Option B: Workspace Config (`strata config set`)

Requires: strata sln init to have been run — writes to .strata/cli.yaml.

Store preferences in the workspace itself. Because .strata/ is workspace-scoped, different workspaces can have different defaults.

strata config set output json    # all commands in this workspace default to JSON output
strata config set verbose true
strata config list               # show current workspace defaults
strata config unset output       # remove the override, fall back to built-in default

Stored in .strata/cli.yaml:

values:
  output: json
  verbose: false
  quiet: false

Loaded at startup via Click’s default_map, then merged with env vars and explicit flags.

Pros:

Workspace-scoped — different workspaces, different defaults
Committed to source control (or gitignored, your choice)
Self-documenting via strata config list

Cons:

Requires an initialised workspace
Not available before strata sln init

Resolution Order (highest to lowest priority)

--flag explicitly passed
  └─ STRATA_* environment variable
      └─ .strata/cli.yaml (strata config set)
            └─ built-in default (hardcoded in CLI)

This means:

CI/CD: use --work-path or STRATA_WORK_PATH — explicit, deterministic, no filesystem dependency
Local dev: run strata config set output console once after strata sln init and forget about it
One-off override: prefix any command with STRATA_OUTPUT=json strata validate

Work Path Resolution (special case)

--work-path / STRATA_WORK_PATH additionally supports directory walking: if neither the flag nor the env var is set, the CLI walks up from CWD looking for .strata/. This means on a local machine you can cd anywhere inside the workspace tree and commands just work.

/myworkspace/
  .strata/          ← found here → work-path resolved
  repo-a/
    src/
      ← user runs `strata build` here, walks up two levels, finds it
  repo-b/

In CI/CD pipelines the checkout directory is rarely predictable, so always set STRATA_WORK_PATH or --work-path explicitly there.

Keyword Reference

The following keywords are common CLI verbs and their typical meaning. Use --output json for automation when appropriate.

Keyword	Use
`list`	Enumerate multiple items (short summary). Example: `strata config list` — shows keys and brief values.
`show` / `get`	Display a single resource’s content or value; include source with `--source`. Example: `strata config show output`.
`dump` / `view`	Output the full merged config or raw file (machine-friendly). Example: `strata config dump --output json`.
`info` / `describe`	Human-friendly overview or summary of workspace state (counts, last run, repos). Example: `strata workspace info`.
`status`	Operational or sync state for resources (repos, deployments). Example: `strata repo status <name>`.
`show-file`	Explicitly show raw file content (alias of `show` for files). Example: `strata config show cli.yaml`.
`source`	Show origin of a value (env, `cli.yaml`, builtin). Example: `strata config show output --source`.