CLI Reference

    Complete reference for the StructKit command-line interface.

    Overview

    structkit {info,validate,generate,list,sources,config,generate-schema,mcp,completion,init} ...

    Global Options

    • -h, --help — Show help message
    • -l LOG, --log LOG — Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
    • -c CONFIG_FILE, --config-file CONFIG_FILE — Path to configuration file
    • -i LOG_FILE, --log-file LOG_FILE — Path to log file

    Commands

    generate

    Generate the project structure.

    structkit generate [-s STRUCTURES_PATH] [-d] (--diff)
  [-v VARS] [-b BACKUP] [-f {overwrite,skip,append,rename,backup}]
  [--mappings-file FILE] [-o {console,file}]
  [structure_definition] [base_path]

    Defaults: structure_definition → .structkit.yaml, base_path → .

    The legacy .struct.yaml is still picked up when no .structkit.yaml exists.

    info

    structkit info [-s STRUCTURES_PATH] structure_definition

    validate

    structkit validate yaml_file

    list

    structkit list [-s STRUCTURES_PATH] [--source NAME]

    config — inspect layered configuration

    Print the effective configuration after layering. Precedence: CLI args > project config (.structkit.yaml or --config-file) > user config (~/.config/struct/config.yaml) > built-in defaults.

    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.

    Hook safety flags

    • --no-hooks — skip pre/post hooks (env: STRUCTKIT_NO_HOOKS=true)
    • --non-interactive — skip the hook confirmation prompt (env: STRUCTKIT_NON_INTERACTIVE=true); hooks still run unless --no-hooks is set
    • --hooks-allowlist PATH — allowlist file (env: STRUCTKIT_HOOKS_ALLOWLIST); .struct-hooks-allowlist is auto-detected in the cwd

    sources — manage named structure sources

    Keywords: sources, structkit sources, STRUCTKIT_SOURCES_CONFIG, STRUCTKIT_SOURCES_CACHE, --source, named sources, git-backed sources.

    Manage named custom structure sources. Sources support local filesystem directories, GitHub repositories, and git-backed repositories. Configure with STRUCTKIT_SOURCES_CONFIG; cache git clones under STRUCTKIT_SOURCES_CACHE.

    structkit sources [--config-path CONFIG_PATH] {list,add,remove,show,validate} ...

# Examples
structkit sources add company ./templates
structkit sources add platform httpdss/platform-structures
structkit sources add versioned github://httpdss/platform-structures@v1/structures
structkit sources list
structkit sources show platform
structkit sources validate platform
structkit sources remove company

# Use a configured source
structkit list --source company
structkit generate company/project/python ./app

    PATH_OR_URL may be a local directory, GitHub shorthand (owner/repo), github://owner/repo@ref/subdir, or a git URL (HTTPS, SSH, or file://). Git-backed sources are cloned into the StructKit sources cache and refreshed with git fetch when resolved or validated. Resolution precedence: --structures-path/STRUCTKIT_STRUCTURES_PATH, then --source or <name>/<structure>, then bundled structures.

    generate-schema

    structkit generate-schema [-s STRUCTURES_PATH] [-o OUTPUT]

    completion

    structkit completion install [bash|zsh|tcsh|fish]

# Print a completion script (bash, zsh, tcsh, fish)
structkit --print-completion fish

    Bash, Zsh, and Tcsh scripts come from shtab; Fish scripts are generated by StructKit.

    init

    structkit init [path]

    Creates a .structkit.yaml if it doesn't exist. Non-destructive.

    Examples

    Common examplesbash
    # Generate using defaults
structkit generate

# Generate with a built-in definition
structkit generate python-basic ./my-project

# Generate with template variables
structkit generate -v "project_name=MyApp,author=John" file://structure.yaml ./output

# Dry run with diff preview
structkit generate -d --diff file://structure.yaml ./output

# Skip existing files
structkit generate -f skip file://structure.yaml ./output

# Console output
structkit generate -o console file://structure.yaml ./output

    File-Local sources: & Slash Refs

    A .structkit.yaml can declare its own sources: block. Nested structs inherit the parent's source context. Use query-style refs for branch names that contain slashes.

    Copy-paste: slash-ref source

    Branch names with slashes cannot be embedded in github://owner/repo@ref/subdir. Use a ?ref= query instead:

    Terminalbash
    # Add a source pinned to a branch with a slash in its name
structkit sources add release_branch github://httpdss/platform-structures/structures?ref=release/1.x

# Generate from the slash-ref source
structkit generate release_branch/github/actions-ci ./my-project

# Preview the diff without writing files
structkit generate release_branch/github/actions-ci ./my-project --dry-run --diff

    Copy-paste: file-local generate workflow

    Commit the source pinning inside the .structkit.yaml so anyone can run the same generation command without first configuring global sources.

    .structkit.yamlyaml
    sources:
  platform:
    url: github://httpdss/platform-structures@v1.2.0/structures
  release_branch:
    url: github://httpdss/platform-structures/structures?ref=release/1.x

folders:
  - ./:
      struct:
        - platform/python/service       # nested structs inherit "platform"
        - release_branch/github/actions-ci
      with:
        service_name: demo-api
    Terminalbash
    # Generate using the file-local sources above
structkit generate .structkit.yaml ./app

# Preview without writing files
structkit generate .structkit.yaml ./app --dry-run --diff

# Run the bundled versioned-sources example
structkit generate examples/versioned-sources/.structkit.yaml /tmp/structkit-versioned-sources-demo
structkit generate examples/versioned-sources/.structkit.yaml /tmp/structkit-versioned-sources-demo --dry-run --diff

    Related

    Previous

    Shell Completion

    Next

    Built-in Structures