scaffold-context — Runtime configuration background knowledge
User-invocable: false Auto-triggerable: true
Triggers when: User asks about scaffoldrc setup, scaffold resolution, environment variables, authentication, or how scaffold finds templates.
ScaffoldRC Location
The scaffoldrc file is resolved in this order:
- •
--scaffoldrcCLI flag - •
SCAFFOLDRCenvironment variable - •
~/.scaffold/scaffoldrc.yml(legacy, only if it exists on disk) - •
$XDG_CONFIG_HOME/scaffold/scaffoldrc.yml(default:~/.config/scaffold/scaffoldrc.yml)
If the file doesn't exist, it's created automatically as an empty file. An empty file is valid and uses all defaults.
Use scaffold dev migrate to move legacy ~/.scaffold/ paths to XDG locations.
Scaffold Reference Resolution
When scaffold new <ref> is called, the reference resolves through:
- •Aliases — exact match against scaffoldrc
aliaseskeys → replaced with alias value - •Shorts — colon syntax (e.g.,
gh:org/repo) expanded via scaffoldrcshorts→ URL - •Remote URL — cloned to cache directory, specific version/branch/tag supported
- •Absolute path — used directly
- •Relative path (contains
/) — joined with current working directory - •Bare name — searched in all
--scaffold-dirdirectories (default:.scaffold/)
If resolution fails interactively, fuzzy matching runs against all known scaffolds with a "did you mean?" prompt. In --no-prompt mode, the error is returned directly.
Authentication
For private repositories, configure auth in scaffoldrc. If no auth is configured and a remote requires it, the CLI prompts interactively (unless --no-prompt).
See scaffoldrc-reference.md for the auth section schema.
Environment Variables
| Variable | Maps to | Description |
|---|---|---|
SCAFFOLDRC | --scaffoldrc | ScaffoldRC file path |
SCAFFOLD_DIR | --scaffold-dir | Template search directories |
SCAFFOLD_CACHE | --cache | Cache directory for remote scaffolds |
SCAFFOLD_LOG_LEVEL | --log-level | Log level (debug, info, warn, error) |
SCAFFOLD_SETTINGS_LOG_LEVEL | --log-level | Log level (alt) |
SCAFFOLD_SETTINGS_LOG_FILE | --log-file | Log file path |
SCAFFOLD_SETTINGS_THEME | --theme | UI theme |
SCAFFOLD_THEME | --theme | UI theme (alt) |
SCAFFOLD_SETTINGS_RUN_HOOKS | --run-hooks | Hook execution policy |
SCAFFOLD_OVERWRITE | --overwrite | Overwrite existing files |
SCAFFOLD_FORCE | --force | Allow dirty git tree |
SCAFFOLD_OUT | --output-dir | Output directory |
CLI flags take precedence over environment variables, which take precedence over scaffoldrc settings.
Default Paths
| Purpose | XDG Path | Legacy Path |
|---|---|---|
| ScaffoldRC | $XDG_CONFIG_HOME/scaffold/scaffoldrc.yml | ~/.scaffold/scaffoldrc.yml |
| Cache | $XDG_DATA_HOME/scaffold/templates | ~/.scaffold/cache |
Legacy paths are used if they exist. XDG defaults: ~/.config/ for config, ~/.local/share/ for data.
Cache Behavior
Remote scaffolds (URLs, shorts) are cloned to the cache directory. Use scaffold update to pull latest for all cached scaffolds. The cache directory can be overridden with --cache or SCAFFOLD_CACHE.