Mkarchi Logo
mkarchi

Table of Contents

Need Help?

Check out our community on GitHub.

Join Discussion

Documentation

Comprehensive guide to mkarchi. Learn how to generate project structures, manage ignore patterns, and integrate with AI tools.

1Installation

mkarchi requires Python 3.6 or newer. It is distributed via PyPI and can be installed using pip.

Terminal
pip install mkarchi

Upgrade Note: If you already have mkarchi installed, ensure you are on the latest version (v0.1.7) to access all features described here.

pip install --upgrade mkarchi

Verify that the installation was successful:

Terminal
mkarchi --version

2Quick Start

Get up and running in seconds. Define your structure in a text file and apply it.

  1. Create a structure file (e.g., project.txt).
    project.txt
    project_root/
├── src/
│   ├── main.py
│   └── utils.py
├── tests/
│   └── test_main.py
└── README.md
  2. Run the apply command.
    Terminal
    mkarchi apply project.txt

That's it! mkarchi will create all folders and files defined in your structure.

3Syntax Guide

mkarchi uses a visual, indentation-based syntax. It is designed to be human-readable and easy for LLMs to generate.

1. Hierarchy & Indentation

The structure is determined by tree characters (│, ├──, └──) or simple spaces. You can copy output directly from the tree command on Linux/Mac.

2. File Content Markers

To define content within a file, use the (begincontenu) and (endcontenu) markers.

  • Start: Must be on the same line as the filename.
  • End: Must be on its own line after the content.

3. Comments

Lines starting with # are treated as comments and ignored by the parser.

Complete Syntax Example

advanced_structure.txt
flask_app/
├── app.py (begincontenu)
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello World!"
(endcontenu)
│
├── .gitignore (begincontenu)
__pycache__/
venv/
.env
(endcontenu)
│
└── README.md (begincontenu)
# Flask App
Generated by mkarchi.
(endcontenu)

4CLI Reference

Complete reference for all available commands and flags.

mkarchi apply

mkarchi apply <structure_file>

Parses the specified structure file and creates the directory tree and files relative to the current working directory.

mkarchi give

mkarchi give [options] [output_file]

Scans the current directory and generates a structure file. This is effectively "Reverse Engineering" your project into a generic template.

Options

FlagDescriptionExample
-c, --no-contentGenerate structure only, without file contents.mkarchi give -c
-max=<kb>v0.1.7+Max file size to include (default: 10KB).mkarchi give -max=50
--no-maxv0.1.7+Include ALL file contents, regardless of size.mkarchi give --no-max
--no-ignorev0.1.7+Disable all ignore patterns (includes node_modules, etc).mkarchi give --no-ignore

5Reverse Engineering

The give command is a powerful tool to "demand" the architecture of an existing project. This is perfect for creating templates, backups, or LLM contexts.

Scenario A: Create Template

You have a working React setup and want to reuse it.

mkarchi give base_template.txt

Scenario B: Full Backup

You want to save EVERYTHING into a single text file.

mkarchi give --no-max --no-ignore backup.txt

6Configuration

By default, mkarchi ignores common clutter (node_modules, .git, __pycache__). You can override this behavior using a configuration file.

.mkarchiignore

Create a file named .mkarchiignore in your project root. The syntax is identical to .gitignore.

.mkarchiignore
# .mkarchiignore
# Ignore node_modules directory
node_modules

# Ignore environment files
.env
.env.local

# Ignore all log files
*.log
npm-debug.log*

# Ignore build output
dist/
build/

7AI Workflow

mkarchi bridges the gap between AI code generation and your local filesystem.

The "Prompt-to-Project" Workflow

  1. 1. Prompt your AI

    "Create a Django blog structure using mkarchi syntax..."

  2. 2. Copy Output

    Copy the code block generated by the AI.

  3. 3. Apply locally

    Paste into struct.txt and run mkarchi apply struct.txt.