Seedling-tools 2.4.1

A modular 3-in-1 CLI toolkit to explore, search, and reconstruct directory structures with LLM-ready context support.

Seedling (v2.4.1)

Seedling is a high-performance, 3-in-1 CLI toolkit designed for developers to explore, search, and reconstruct directory structures. Whether you need a beautiful image of your project architecture, a way to spawn a project from a text blueprint, or a context-optimized codebase skeleton for LLMs, Seedling has you covered.

Read this document in other languages: 简体中文

---

Installation

Seedling is designed to be installed globally via pipx for a clean, isolated environment.

pipx install Seedling-tools

One-Click Setup

• Windows: Run ./install.bat
• macOS / Linux: Run bash install.sh

Developer / Manual Install

If you are modifying the source code, use Editable Mode:

pipx install -e . --force

---

Python Library Usage

You can now use Seedling's core features directly in your Python code via the ScanConfig engine:

import seedling
from seedling.core.filesystem import ScanConfig

# 1. Initialize configuration (Set quiet=True to suppress CLI progress bars)
config = ScanConfig(max_depth=2, quiet=True)

# 2. Generate directory tree lines
stats = {"dirs": 0, "files": 0}
lines = seedling.scan_dir_lines("./src", config, stats)
print("\n".join(lines))

# 3. Search for specific items programmatically
exact, fuzzy = seedling.search_items(".", keyword="utils", config=config)

# 4. Reconstruct a project from a blueprint
seedling.build_structure_from_file("blueprint.md", "./new_project")

---

CLI Reference

Seedling 2.4.1 uses a clean, explicit argument system.

1. scan - The Explorer

Used for scanning directories, extracting code skeletons, or searching for items. Note: --full and --skeleton are mutually exclusive.

Argument	Description
target	Target directory for scanning or searching (Defaults to .).
--find, -f	Search Mode. Fast CLI search (Exact & Fuzzy). Combine with --full to export a code report.
--format, -F	Output format: md (default), txt, json, or image.
--name, -n	Custom output filename.
--outdir, -o	Where to save the result.
--showhidden	Include hidden files in the scan.
--depth, -d	Maximum recursion depth.
--exclude, -e	List of items to ignore. Smart parse: auto-reads .gitignore files or accepts globs.
--include	[NEW] Only include files/directories matching patterns (e.g., --include "*.py").
--type, -t	[NEW] Filter by file type: py, js, ts, cpp, go, java, rs, web, json, yaml, md, shell, all.
--regex	[NEW] Treat -f pattern as regular expression.
--grep, -g	[NEW] Search inside file contents (Content Search Mode).
-C, --context	[NEW] Show N lines of context around grep matches.
--analyze	[NEW] Analyze project structure, type, dependencies, and architecture.
--full	Power Mode. Appends the full text content of all scanned source files.
--skeleton	[Experimental] AST Code Skeleton extraction. Strips logic, retains signatures.
--text	Smart Filter. Only scan text-based files (ignores binary/media).
--delete	Cleanup Mode. Permanently delete items matched by --find (Interactive TTY only).
--dry-run	[NEW] Preview deletions without executing (use with --delete).
--verbose / -q	Verbose mode (-v) or Quiet mode (-q).

2. build - The Architect

Turn a text-based tree into a real file system, or restore a project from a snapshot.

Argument	Description
file	The source tree blueprint file (.txt or .md).
target	Where to build the structure (Defaults to current directory).
--direct, -d	Direct Mode. Bypass prompts to instantly create a specific path.
--check	Dry-Run. Simulate the build and report missing/existing items.
--force	Force Mode. Overwrite existing files without skipping.

---

New in v2.4.1 - Bug Fixes & Improvements

Security

• --dry-run Mode: Preview deletions before executing with --delete:

  scan . -f "temp_*" --delete --dry-run
  

Compatibility

• Python 3.9+ Required for --skeleton: Clear error message for Python 3.8 users
• Pillow as Optional Dependency: Install with pip install Seedling-tools[image] only if you need image export

Performance

• Accurate Memory Calculation: Fixed memory tracking to prevent OOM crashes on high-Unicode files
• Conservative Memory Threshold: Reduced to 80% for additional safety

JSON Output Mode

Export directory structures as structured JSON for programmatic consumption:

scan . -F json -o structure.json

File Type & Include Filters

Filter by file type or custom patterns:

scan . --type py -d 3
scan . --include "*.md" --include "*.txt"

Regex Search Mode

Use regular expressions in search:

scan . -f "test_.*\.py" --regex

Content Search (Grep Mode)

Search inside file contents with context:

scan . --grep "TODO" -C 3 --type py
scan . -g "def main" -C 2

Project Analysis

Analyze project structure and dependencies:

scan . --analyze

---

Project Structure (v2.4.1)

Seedling/
├── docs/                      # Documentation & Changelogs
│   ├── CHANGELOG.md           # English version history
│   ├── CHANGELOG_zh.md        # Chinese version history
│   └── README_zh.md           # Chinese documentation
├── seedling/                  # Core Package
│   ├── commands/              # CLI Command Routers
│   │   ├── build/             # Build logic
│   │   └── scan/              # Scan logic
│   │       ├── __init__.py    # Command routing
│   │       ├── analyzer.py    # [NEW] Project analysis
│   │       ├── explorer.py    # Directory scanning
│   │       ├── grep.py        # [NEW] Content search
│   │       ├── json_output.py # [NEW] JSON output
│   │       └── search.py      # File search
│   ├── core/                  # Shared Engines
│   │   ├── filesystem.py      # Iterative DFS, ScanConfig & Filtering
│   │   ├── io.py              # File R/W, Fence Collision & Path Safety
│   │   ├── logger.py          # Centralized CLI Formatter
│   │   ├── sysinfo.py         # Hardware Probe
│   │   └── ui.py              # Animations & CI/CD checks
│   ├── __init__.py            # Public API & Metadata
│   └── main.py                # CLI Entry Point Router
├── tests/                     # Unit Tests (Core, Edge Cases, IO & v2.4 features)
├── install.bat                # Windows one-click installer
├── install.sh                 # Linux/macOS one-click installer
├── LICENSE                    # MIT License
├── pyproject.toml             # Build configuration & Package metadata
├── pytest.ini                 # Pytest configuration file
├── README.md                  # Main documentation
└── test_suite.sh              # Automated E2E tests

---

Changelog

Detailed changes for each release are documented in the docs/CHANGELOG.md file.