A modular CLI tool for high-velocity environment scaffolding.

Setting up a new python project often requires the same manual steps: configuring linters, writing Dockerfile, .gitignore and .dockerignore files, setting up virtual environments, and linking IDEs. Protostar automates this boilerplate so you can skip the setup and get straight to writing code.

---

---

📖 Official Documentation

Ready to dive deeper? The README only scratches the surface.

Head over to the Official Documentation for:

• Command Reference: Full flags and capabilities for init.
• Domain Presets: Matrices for Scientific, Astrophysics, ML, DSP, Embedded, REST API, and CLI Application workflows.
• Configuration & Shell Autocomplete: Setting up global defaults, CLI autocompletion, and advanced AST overrides.
• Architecture Mechanics: Deep dives into the Orchestrator, Executor, and Manifest lifecycle.

---

💡 Design Philosophy

Protostar is built to save you time and stay out of your way. It adheres to a strict separation of concerns to avoid generating bloated artifacts you'll inevitably just delete manually:

1. Foundational Scaffolding: The protostar init command is designed to be run exactly once at the inception of a repository to lay the architectural groundwork, locking in your dependency managers and directory structures.

2. Manifest-First, Side-Effects-Last: Many bootstrapping scripts run a sequence of shell commands and fail unpredictably midway through. Protostar separates state definition from execution. Modules declare their requirements into a centralized EnvironmentManifest. Disk I/O and subprocesses only execute in a single, deterministic phase at the very end.

3. Fail Loud, Fail Early: Pre-flight checks ensure all system dependencies (like uv, git, or direnv) are present before any state is mutated.

4. Non-Destructive by Default: Protostar never blindly overwrites your existing work. It dynamically appends to .gitignore files, intelligently merges IDE JSON configurations, uses deterministic AST modification to deep-merge TOML configurations, and safely aborts if generated files already exist.

5. Actionable Telemetry: When things break, Protostar bubbles up the exact stderr so you know immediately if a network request or dependency resolution failed. For unexpected internal crashes, it automatically generates a URL-encoded GitHub issue containing your system environment vector to eliminate debugging entropy. You can also append the global --verbose (or -v) flag to any command to enable rich, detailed stack traces and debug-level logging.

---

⚡️ Performance & Latency Isolation

Protostar is built to be lightweight, so Python's startup overhead never slows down your local development.

We measure initialization latency using two benchmarking approaches:

1. Fast-Path Execution: Measures the latency of non-interactive commands (e.g., protostar help init).
2. TUI-Path Execution: Measures the overhead of triggering the interactive questionary wizards.

Our CI pipeline enforces a strict performance budget using hyperfine, gating any PR that introduces significant regressions in either path. We maintain historical tracking to ensure long-term architectural stability rather than chasing absolute CI metrics (which are subject to heavy VM variance).

• View CI Trends: Performance Dashboard

---

📦 Installation

macOS (Homebrew)

brew install jacksonfergusondev/tap/protostar

Universal (uv)

For isolated CLI tool installation on any OS, uv is highly recommended:

uv tool install protostar

Universal (pip)

pip install protostar

Note: If you install Protostar into an existing Python environment with pip, it will bring in questionary and prompt_toolkit for the interactive wizard. For guaranteed isolation and to avoid dependency conflicts, prefer uv tool or Homebrew.

---

🚀 Quick Start

Protostar is designed to be run right after you mkdir a new project.

The Interactive Wizard

If you run protostar without any arguments, it launches an interactive Terminal User Interface (TUI).

The wizard will first ask if you want to scaffold using a Template. Templates are the gold standard of Protostar, instantly wiring together complex tools, dependencies, and directory structures. You can choose from built-in domain templates (like astro or cli), select your own custom global aliases, or build an environment from scratch.

mkdir orbital-mechanics-sim
cd orbital-mechanics-sim
protostar

Headless Scaffolding & Tri-State Toggles

For rapid, repeatable initialization, bypass the TUI entirely. Templates are the primary way to drive Protostar headlessly:

protostar init --template cli

Because Protostar uses tri-state toggling, you always remain in control. You can load a template but explicitly override its default opinions by passing --<flag> to force a tool on, or --no-<flag> to force it off:

protostar init --template cli --no-direnv --docker

Result: Scaffolds the cli template, strips out the default direnv scaffolding, and generates container artifacts (Dockerfile, .dockerignore).

To bypass any interactive collision prompts when running in headless CI environments, use --force-merge or --force-replace. You can also explicitly override the target Python version by passing --python-version 3.13.

Portable Templates & Global Aliases

If you want to enforce team-wide standards across multiple repositories, you can host your own custom template TOML files remotely (or store them locally). Use the --from flag to dynamically fetch and inject them. Protostar automatically translates web UI links into raw text links for GitHub, GitLab, Bitbucket, Codeberg, and Sourcehut, and natively supports unpacking .zip/.tar.gz repository archives.

protostar init --from https://raw.githubusercontent.com/YourOrg/standards/main/backend.toml

Global Aliases: Instead of typing long URLs, you can register templates in your global configuration (~/.config/protostar/config.toml):

[templates]
backend = "https://raw.githubusercontent.com/YourOrg/standards/main/backend.toml"

Now you can run protostar init --template backend anywhere, and it will automatically appear alongside built-ins in your interactive wizard.

Note: To prevent unauthorized remote code execution, external templates containing shell tasks are secured behind an explicit Interactive Trust Dialog. Templates mapped as global aliases bypass this prompt automatically.

---

🤝 Collaboration

This tool uses a highly decoupled, plugin-style architecture. The CLI parser dynamically evaluates module registries at runtime.

• To add support for a new core tool (e.g., a linter or formatter): Subclass BootstrapModule.
• To define a new domain workflow: Author a declarative TOML Template.

We maintain strict engineering standards to ensure reliability, including 100% type-hinting, isolated pytest environments (mocked subprocesses and tmp_path disk isolation), and automated ruff formatting.

Please see the Documentation for full details on our development setup, architectural rules, and pull request guidelines.

📧 Contact

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.