CLI reference

Overview

Options, exit codes, and output formats shared by every Socotra command.

Global options apply to every command and must appear before the command name.

Global options

Option	Alias	Type	Default	Description
`--working-dir`	`-d`	string	cwd	Working directory for YAML discovery and all operations
`--config`	`-c`	string	null	Explicit path to socotra.yaml (auto-searches upward)
`--verbose`	`-v`	bool	false	Enable verbose output
`--log-file`	—	string	null	Path to JSON Lines debug log file
`--detailed-exit-codes`	—	bool	false	Distinguish success-with-changes from success-no-changes
`--version`	`-V`	flag	—	Print version and exit immediately
`--help`	`-h`	flag	—	Display Spectre.Console help page

Output formats

Format	Behavior
`text`	Coloured Spectre.Console output with prompts, spinners, progress bars, and risk indicators
`json`	Structured JSON to `stdout`; info to `stderr`; `--output json` implies `--auto-approve` for `apply`

Exit code summary

Code	Meaning	Notes
0	Success (no changes)	Default when no work was needed
1	Error	Validation, network, filesystem, missing template
2	Success with changes	Only with `--detailed-exit-codes`

Change types and risk levels

Change	Risk	Indicator
`CreateSolution`	Low	+ green
`AddProject`	Low	+ green
`AddToSolution`	Low	+ green
`AddPackage`	Low	+ green
`AddSolutionFolder`	Low	+ green
`ApplyTemplate`	Low	+ green
`AddProjectReference`	Medium	~ yellow
`UpdatePackage`	Medium	~ yellow
`UpdateTargetFramework`	Medium	~ yellow
`UpdateProperty`	Medium	~ yellow
`RemoveProjectReference`	High	− red
`RemovePackage`	High	− red
`RemoveSolutionFolder`	High	− red
`RemoveTemplate`	High	− red

Detailed exit codes in CI

When --detailed-exit-codes is used, scripts can distinguish "nothing to do" (exit 0) from "changes applied" (exit 2). Useful for gating follow-up steps.

ci.ps1

dotnet socotra plan --detailed-exit-codes
if ($LASTEXITCODE -eq 2) {
    dotnet socotra apply --auto-approve
    git add .
    git commit -m "Apply socotra changes"
}

Schema 1.1 · CLI 1.0

PreviousPipeline architecture Next socotra init