Skip to content

Cheat Sheet

Jump to bottom
Kaapers edited this page Oct 5, 2026 · 1 revision

Everything you need to use StructureX on one page. For full details, see the README.

Install

Get the file for your operating system from Releases. They are not interchangeable.

OS Download Guide
Windows 10/11 structurex-windows-x86_64.zip windows/README.md
macOS (Apple M1–M4) structurex-macos-arm64.tar.gz macOS/README.md
macOS (Intel) structurex-macos-x86_64.tar.gz macOS/README.md
Linux (x86_64) structurex-linux-x86_64.tar.gz linux/README.md

Check it works: structurex --version

Command

structurex -i <TREE FILE> [-t <TARGET DIR>] [-d] [-y]
Option Meaning Default
-i, --input <PATH> Tree text file to read required
-t, --target <PATH> Where to create the structure . (current folder)
-d, --dry-run Show the plan only and write nothing off
-y, --yes Don't ask [y/N] and create right away off
-h, --help Show help
-V, --version Show version

Everyday recipes

I want to… Command
Preview without writing structurex -i tree.txt -t ./app -d
Create, with a y/N prompt structurex -i tree.txt -t ./app
Create without a prompt (scripts, CI) structurex -i tree.txt -t ./app -y
Create in the current folder structurex -i tree.txt
Save the plan to a file structurex -i tree.txt -d > plan.txt
Copy a folder's layout (Linux/macOS) tree -F my-template > tree.txt
Copy a folder's layout (Windows) tree /F /A my-template > tree.txt

Re-running is safe: existing files are never overwritten and are only shown as (exists, skipping).

Tree file syntax

my-app/                 # trailing / = folder
├── Cargo.toml          # no trailing / = file
├── src/
│   ├── main.rs
│   └── utils/
│       └── mod.rs
├── docs/               # empty folder: needs the /
└── scripts/build.py    # a/b/c on one line creates the folders too
Rule Example
Folder ends with / or has entries under it
File everything else: main.rs, Makefile, .gitignore
Comment # at the start of a line or after a space: src/ # code
# inside a name is kept C#/, issue#12.md
Blank lines ignored
Indentation any consistent width; a tab counts as 4 columns

Accepted tree styles (you can mix them):

├── └── │        Unicode (tree command, hand-drawn)
|-- `-- |        ASCII
+--- \---        Windows tree /A
(spaces/tabs)    plain indentation

Also skipped automatically: tree's . root line, its N directories, M files footer, and Windows' Folder PATH listing… / Volume serial number… / C:. lines.

File encodings: UTF-8 (with or without BOM) or UTF-16 (with BOM), with Windows or Unix line endings.

Starter code in new files

File Gets
Cargo.toml [package] named after its folder, edition 2024
CMakeLists.txt C++20 project + add_executable with the .cpp files under it
README.md # <folder name>
*.rs // Rust module (main.rs also gets fn main())
*.py #!/usr/bin/env python3 + docstring (main.py also gets a main guard)
*.cpp *.cc *.cxx main.* → int main(), others → #include of a matching header
*.hpp *.h *.hh #pragma once
anything else empty file

Reading the output

You see Meaning
[DIR] path/ folder to create
[FILE] path file to create
(exists, skipping) already there and left untouched
(will be created) next to Target the target folder doesn't exist yet
warning: … no extension and no children created as a file; add / if you meant a folder
created path written to disk

Exit codes

Code Meaning
0 success, dry run, or nothing to do
1 error, or you answered no at the prompt
2 wrong command-line options

Always rejected (before anything is written)

  • absolute paths (/etc/x, and C:\x on Windows) and .., so nothing is ever written outside the target
  • empty parts (a//b)
  • a folder in the tree where a file already exists on disk, or the reverse
  • symlinks that lead outside the target

On Windows only:

  • names with < > : " | ? * or \
  • names ending in . or a space
  • reserved names: CON PRN AUX NUL COM1–COM9 LPT1–LPT9, also with an extension (aux.rs)
  • names longer than 255 characters

Troubleshooting

Problem Fix
command not found / not recognized Add the program's folder to your PATH, then open a new terminal
stdin is not a terminal; re-run with --yes You're in a script or pipe; add -y
not valid UTF-8 or UTF-16 Re-save as UTF-8, or on Windows use tree /F /A > tree.txt
is declared as a directory but a file exists Rename or remove that file, or fix the tree
Windows: "Windows protected your PC" More info → Run anyway
macOS: "developer cannot be verified" xattr -d com.apple.quarantine structurex
Exec format error / bad CPU type / can't run on your PC Wrong download; pick the file for your OS and CPU

For contributors

cargo test                                  # all tests
cargo clippy --all-targets -- -D warnings   # lints
cargo fmt                                   # format
cargo run -- -i examples/tree.txt -d        # try it without installing
Build for… Command Output
Linux ./linux/build.sh linux/bin/structurex
macOS ./macOS/build.sh macOS/bin/structurex
Windows powershell -ExecutionPolicy Bypass -File .\windows\build.ps1 windows\bin\structurex.exe

Day-to-day git:

git status
git add -A
git commit -m "What changed"
git push

Release a new version (here, 0.2.0):

  1. Set version = "0.2.0" in Cargo.toml, then run cargo build.
  2. Commit and push: 
    git commit -am "Release v0.2.0"
git push
  3. Wait for CI to go green, then tag and push the tag: 
    git tag v0.2.0
git push origin v0.2.0

GitHub Actions then builds and publishes all four downloads. The tag must match the Cargo.toml version.

StructureX

Clone this wiki locally