Scaffolder

A command-line tool to generate folder and file structures from YAML templates.

Features

• 🚀 Fast: Uses asynchronous I/O for efficient file operations
• 🛠️ Simple: Define your project structure in a simple YAML file
• 🎨 Visual: Rich console output with color-coded status messages and tree visualization
• 🔄 Non-destructive: Asks for confirmation before overwriting existing files
• 🧩 Flexible: Creates files with or without content, nested directories, and more
• 📊 Preview: Visualize your project structure before generating it
• 🔧 Templates: Built-in templates for common project structures

Installation

pip install scfldr

Or install from source:

git clone https://github.com/utkarshg1/scfldr.git
cd scfldr
pip install -e .

Usage

Creating Your Project Structure

Create a YAML template file to define your desired file structure:

# template.yaml
src:
  main.py: |
    def main():
        print("Hello, world!")

    if __name__ == "__main__":
        main()
  utils:
    helpers.py: |
      def add(a, b):
          return a + b
docs:
  README.md: |
    # My Project

    This is a sample project.
tests:
  test_main.py: |
    def test_sample():
        assert True
# Example with append mode
logs:
  app.log: # Standard write mode (overwrites if file exists)
    content: |
      # Log file initialized
      # App started
  error.log: # Append mode (adds content if file exists)
    content: |
      # Error log entry
      # Will be appended if the file exists
    mode: a

Then generate your project structure:

scfldr generate-structure --template template.yaml --output my_project

The tool will:

1. Ask for confirmation before overwriting existing files
2. Display a colorful tree visualization of the generated structure
3. Show real-time progress with color-coded status messages

Creating Example Templates

You can quickly create example template files:

scfldr create-example --type basic --output my_template.yaml
scfldr create-example --type web --output web_template.yaml
scfldr create-example --type python_package --output pkg_template.yaml

You can also print the raw template content to the terminal for easy copying:

scfldr create-example --type basic --print-raw

Previewing Structure

Preview the structure defined in your template without generating files. This will display a colorful tree visualization of the project structure:

scfldr show-structure --template template.yaml

Checking Version

You can check the installed version of Scaffolder:

scfldr --version

Command Line Options

Usage: scfldr [COMMAND] [OPTIONS]

Generate folder/file structure from a YAML template.

Commands:
  generate-structure     Generate a project structure from a YAML template
  show-structure         Preview the directory structure from a YAML template
  create-template-file   Create a YAML template file from predefined examples
  create-example         Generate an example YAML template file

Options:
  --help                 Show this message and exit
  --version, -V         Show version and exit

Generate Structure Options:
  --template PATH, -t PATH  Path to the YAML template. [default: template.yaml]
  --output PATH, -o PATH    Output directory root. [default: .]
  --force, -f / --no-force  Overwrite existing output directory if it exists.

Show Structure Options:
  --template PATH, -t PATH  Path to the YAML template. [default: template.yaml]

Create Template File Options:
  TEMPLATE_NAME          Name of the template to create (e.g., 'basic', 'web', 'python_package')
  --output-path PATH     Output path for the YAML template file. [default: template.yaml]
  --print-raw, -p        Print raw template content to terminal for easy copying

Create Example Options:
  --output PATH, -o PATH    Path to save the example template. [default: template.yaml]
  --type TEXT               Type of template to generate (basic, web, python_package). [default: basic]
  --force, -f / --no-force  Overwrite existing file if it exists.
  --print-raw, -p           Print raw template content to terminal for easy copying

YAML Template Format

The YAML template follows a simple structure:

• Keys represent directory or file names
• Generated templates use literal style (|) for multiline strings to preserve formatting
• Values represent:
  • For directories: A nested dictionary defining child entities
  • For files:
    • String content (can be multiline using YAML's | syntax)
    • OR a dictionary with content and optional mode keys
      • mode: a to append content to an existing file
      • mode: w (default) to create or overwrite a file
  • For empty directories: An empty dictionary {}

Examples:

# Basic structure
project:
  src:
    main.py: |
      def main():
          print("Hello, world!")
    utils: {} # Empty directory
  README.md: "# Project Title"

# Structure with append mode
project:
  src:
    main.py: |
      def main():
          print("Hello, world!")
  logs:
    app.log: # Standard write mode (default)
      content: "Log entry"
    error.log: # Append mode
      content: "Error message"
      mode: a # 'a' for append, 'w' for write (default)

Predefined Templates

Scaffolder comes with several predefined templates that you can use to quickly start a project:

Basic Template

A simple project structure with source files, documentation, and tests.

scfldr create-template-file basic --output-path basic_template.yaml

You can also print the raw template content to the terminal:

scfldr create-template-file basic --print-raw

Web Template

A Flask web application with static files, templates, and basic setup.

scfldr create-template-file web --output-path web_template.yaml

Python Package Template

A standard Python package structure with tests, setup.py, and more.

scfldr create-template-file python_package --output-path package_template.yaml

Development

Requirements

• Python 3.10+
• Dependencies:
  • typer
  • pyyaml
  • asyncio
  • aiofiles
  • rich

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.