Configuration Reference

Complete reference for StructKit YAML configuration files.

Config Layering

Separate from structure files, StructKit reads CLI defaults from layered configuration. Precedence, highest first: CLI args → project config (--config-file) → user config → built-in defaults.

User config: ~/.config/struct/config.yaml
Project config: a YAML file you pass explicitly with --config-file <path>; it is not auto-discovered.

.structkit.yaml is the default structure definition file name (used by structkit init and generate); the legacy .struct.yaml is still read. It is not loaded as CLI configuration; use --config-file for project-level settings.

Built-in defaults: file_strategy: overwrite, input_store: /tmp/structkit/input.json, log: INFO, non_interactive: false, output: file.

Inspect the resolved configuration:

Terminalbash

structkit config print
structkit config print --format json

Supported keys: structures_path, source, input_store, file_strategy, backup, global_system_prompt, non_interactive, output, log, log_file.

~/.config/struct/config.yamlyaml

file_strategy: backup
input_store: ~/.cache/structkit/input.json
structures_path: ~/my-structures
log: WARNING

Top-Level Keys

Key	Type	Description
project_name	string	Name of the project (used as root directory)
structure	list	File and directory structure definition
variables	dict	Custom template variables
hooks	dict	Before/after generation commands
remote_sources	dict	Remote content definitions
mappings	dict	File-to-template mappings

Structure Definition

Define files and directories in a nested YAML list. Directories end with /.

structure:
  # Empty directory
  - logs/

  # Empty file
  - config.ini

  # File with inline content
  - README.md:
      content: |
        # {{ project_name }}
        Welcome!

  # File from remote source
  - .gitignore:
      source: https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore

  # Nested directories
  - src/:
    - app/:
      - main.py
      - routes/:
        - api.py

Variables & Templates

StructKit uses Jinja2-style template syntax for variable substitution.

variables:
  author: "Jane Doe"
  license: "MIT"
  python_version: "3.11"

structure:
  - setup.cfg:
      content: |
        [metadata]
        name = {{ project_name }}
        author = {{ author }}
        license = {{ license }}
        
        [options]
        python_requires = >={{ python_version }}

Hooks

Run commands before or after project generation.

hooks:
  before:
    - echo "Starting project generation..."
  after:
    - cd {{ project_name }} && git init
    - cd {{ project_name }} && pip install -e .
    - echo "Project {{ project_name }} is ready!"

Remote Sources

Fetch content from URLs, GitHub repositories, or Gists.

remote_sources:
  gitignore:
    url: https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
  license:
    url: https://api.github.com/licenses/mit
    field: body

structure:
  - .gitignore:
      source: gitignore
  - LICENSE:
      source: license

Filters: `latest_release`

Signature: latest_release(repo_name, strip_v=false, return_sha=false). Both options are optional and appended, so existing one-argument calls are fully backward compatible.

Parameter	Type	Default	Description
repo_name	str	required	GitHub repository in `owner/name` form
strip_v	bool	false	Version mode only: removes exactly one leading lowercase `v` (`v1.2.3` → `1.2.3`, `vv1.2.3` → `v1.2.3`, `V1.2.3` unchanged)
return_sha	bool	false	Returns the commit SHA identified by the release tag instead of the tag name

files:
  - release.txt:
      content: |
        # v3.3.0 (unchanged default output)
        {{@ "httpdss/structkit" | latest_release @}}

        # 3.3.0 (strip one leading lowercase "v")
        {{@ "httpdss/structkit" | latest_release(strip_v=true) @}}

        # 0123456789abcdef0123456789abcdef01234567 (release commit)
        {{@ "httpdss/structkit" | latest_release(return_sha=true) @}}

With both return_sha=true and strip_v=true, return_sha takes precedence and strip_v is a no-op.
SHA resolution reads the Git tag reference: lightweight tags resolve directly, annotated tags are peeled until a commit is reached. At most 10 Git objects are examined (up to nine annotated-tag hops), and the object ID must be a full 40-character SHA-1 or 64-character SHA-256 hex value.
If the repository is found but the latest-release lookup fails, version mode returns the default branch name and SHA mode returns that branch's head commit SHA; strip_v is never applied to a fallback branch name.
If repository lookup or fallback resolution fails — or a selected release's tag is missing, malformed, cyclic, too deeply nested, or does not resolve to a commit — the filter returns LATEST_RELEASE_ERROR.
Uses PyGithub: set GITHUB_TOKEN for private repositories and authenticated rate limits.

CLI Options

Flag	Description
--dry-run	Preview without creating files
--force	Overwrite existing files
--verbose	Show detailed output
--output-dir	Specify output directory

Usage

Template Variables