Skip to content

CLI Reference

This document provides a reference for the struct command-line interface (CLI).

Overview

The struct CLI allows you to generate project structures from YAML configuration files. It supports both built-in structure definitions and custom structures.

Basic Usage:

struct {info,validate,generate,list,generate-schema,mcp,completion,init} ...

Global Options

These options are available for all commands:

  • -h, --help: Show the help message and exit.
  • -l LOG, --log LOG: Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
  • -c CONFIG_FILE, --config-file CONFIG_FILE: Path to a configuration file.
  • -i LOG_FILE, --log-file LOG_FILE: Path to a log file.

Commands

info

Show information about a structure definition.

Usage:

struct info [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] structure_definition

Arguments:

  • structure_definition: Name of the structure definition.
  • -s STRUCTURES_PATH, --structures-path STRUCTURES_PATH: Path to structure definitions.

validate

Validate the YAML configuration file.

Usage:

struct validate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] yaml_file

Arguments:

  • yaml_file: Path to the YAML configuration file.

generate

Generate the project structure.

Usage:

struct generate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [-n INPUT_STORE] [-d] [--diff] [-v VARS] [-b BACKUP] [-f {overwrite,skip,append,rename,backup}] [-p GLOBAL_SYSTEM_PROMPT] [--non-interactive] [--mappings-file MAPPINGS_FILE] [-o {console,file}] [structure_definition] [base_path]

Defaults when omitted: - structure_definition -> .struct.yaml - base_path -> .

Example: 

struct generate

Arguments:

  • structure_definition (optional): Path to the YAML configuration file (default: .struct.yaml).
  • base_path (optional): Base path where the structure will be created (default: .).
  • -s STRUCTURES_PATH, --structures-path STRUCTURES_PATH: Path to structure definitions.
  • -n INPUT_STORE, --input-store INPUT_STORE: Path to the input store.
  • -d, --dry-run: Perform a dry run without creating any files or directories.
  • --diff: Show unified diffs for files that would be created/modified (works with --dry-run and in -o console mode).
  • -v VARS, --vars VARS: Template variables in the format KEY1=value1,KEY2=value2.
  • -b BACKUP, --backup BACKUP: Path to the backup folder.
  • -f {overwrite,skip,append,rename,backup}, --file-strategy {overwrite,skip,append,rename,backup}: Strategy for handling existing files.
  • -p GLOBAL_SYSTEM_PROMPT, --global-system-prompt GLOBAL_SYSTEM_PROMPT: Global system prompt for OpenAI.
  • --non-interactive: Run the command in non-interactive mode.
  • --mappings-file MAPPINGS_FILE: Path to a YAML file containing mappings to be used in templates (can be specified multiple times).
  • -o {console,file}, --output {console,file}: Output mode.

list

List available structures.

Usage:

struct list [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH]

Arguments:

  • -s STRUCTURES_PATH, --structures-path STRUCTURES_PATH: Path to structure definitions.

generate-schema

Generate JSON schema for available structures.

Usage:

struct generate-schema [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [-o OUTPUT]

Arguments:

  • -s STRUCTURES_PATH, --structures-path STRUCTURES_PATH: Path to structure definitions.
  • -o OUTPUT, --output OUTPUT: Output file path for the schema (default: stdout).

completion

Manage shell completions for struct.

Usage:

struct completion install [bash|zsh|fish]
  • If no shell is provided, the command attempts to auto-detect your current shell and prints the exact commands to generate and install static completion files via shtab.
  • This does not modify your shell configuration; it only prints the commands you can copy-paste.

init

Initialize a basic .struct.yaml in the target directory.

Usage:

struct init [path]
  • Creates a .struct.yaml if it does not exist.
  • Includes:
  • pre_hooks/post_hooks with echo commands
  • files with a README.md placeholder
  • folders referencing github/workflows/run-struct at ./
  • Non-destructive: if .struct.yaml already exists, it is not overwritten and a message is printed.

Examples

Using Defaults

Generate with default structure (.struct.yaml) into current directory:

struct generate

Basic Structure Generation

Generate a structure using a built-in definition:

struct generate python-basic ./my-project

Generate from a custom YAML file:

struct generate file://my-structure.yaml ./output-dir

Using Custom Structures

Generate with custom structure path:

struct generate -s ~/custom-structures python-api ./my-api

Template Variables

Pass template variables to the structure:

struct generate -v "project_name=MyApp,author=John Doe" file://structure.yaml ./output

Dry Run

Test structure generation without creating files:

struct generate -d file://structure.yaml ./output

File Strategies

Handle existing files with different strategies:

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

# Backup existing files
struct generate -f backup -b ./backup file://structure.yaml ./output

Console Output

Output to console instead of creating files:

struct generate -o console file://structure.yaml ./output

Validation

Validate a YAML configuration before generation:

struct validate my-structure.yaml

List Available Structures

List all built-in structures:

struct list

List structures from custom path:

struct list -s ~/custom-structures

Get Structure Information

Get detailed information about a structure:

struct info python-basic

Generate Schema

Generate JSON schema and save to file:

struct generate-schema -o schema.json