ProjectCLI 🚀

Demo (2 minutes):

• Play locally: asciinema play docs/demo.cast
• Convert to plain text (for quick sharing): asciinema convert --output-format txt docs/demo.cast -

Asciinema recording file: docs/demo.cast

The Swiss Army Knife for Project Scaffolding.
Bootstrapping new projects shouldn't require memorizing 50 different CLI commands.

ProjectCLI is an interactive, cross-language project generator. Instead of remembering usage for create-react-app, cargo new, poetry new, laravel new, rails new, etc., just run projectcli.

We handle the complexity of calling the official CLIs for you.

🤔 Why ProjectCLI?

Tool	Problem
create-react-app	JS-only
cargo new	Rust-only
yeoman	heavy & old
projectcli	unified + context-aware

✨ Features

• Multi-Language Support: Rust, Go, Python, JavaScript, TypeScript, PHP, Java, C#, Ruby, Swift, Dart.
• Unified Interface: One interactive wizard to rule them all.
• Smart Context Awareness: Running projectcli inside an existing project automatically offers to add libraries, CI/CD, or Dockerfiles tailored to that language.
• Preflight Checks: Warns you if you are missing required tools (e.g. cargo, go, node) before you start.
• Remote Templates: Clone any GitHub repository and automatically strip .git history for a fresh start.
• CI/CD & Docker: One-click generation of GitHub Actions workflows and Dockerfiles.
• Dev Containers: Generate .devcontainer/devcontainer.json for VS Code / Codespaces.
• License Generator: Add a standard LICENSE file (configurable default).

✅ Safety Guarantees

• ❌ Never writes outside the project folder it creates (guards against path traversal).
• ❌ Never deletes files without an explicit, targeted operation (template clone only removes the cloned .git).
• ✔ Supports --dry-run to preview planned actions without executing them.

🚀 Quick Start

Run instantly with npx:

npx @dawitworku/projectcli@latest

Or install globally:

npm install -g @dawitworku/projectcli
projectcli

🎮 Interactive Mode

Just run projectcli and follow the prompts:

1. Select Language (fuzzy search supported).
2. Select Framework (React, Vue, Next.js, Actix, Axum, Django, FastAPI, etc.).
3. Choose Project Name.
4. (Optional) Add CI/CD or Docker.

🛠 Advanced Usage

V3 Commands

ProjectCLI v3 adds a few focused subcommands:

• projectcli doctor check a repo and optionally apply safe fixes
• projectcli preset list / projectcli preset use <name> manage presets
• projectcli upgrade upgrade generated configs safely (supports --preview)
• projectcli add <feature> add focused features like ci, docker, devcontainer, license, lint, test
• projectcli plugin list / projectcli plugin install <id> enable plugins (and their contributions)

Context Awareness

Run it inside a project to detect the language and offer relevant tools:

cd my-rust-project
projectcli
# Output: "✓ Detected active Rust project"
# Options: [Add GitHub Actions CI], [Add Dockerfile], [Add Dependencies]

Remote Templates

Clone a starter kit from GitHub and make it your own instantly:

projectcli --template https://github.com/example/starter-repo --name my-app

You can also apply extras non-interactively:

projectcli --template https://github.com/example/starter-repo --name my-app --yes --ci --docker --devcontainer --license

Automation / CI Use

Skip the interactive prompts for scripts or specialized workflows:

projectcli --language Rust --framework Actix --name my-api --ci --docker --yes

Preview what would happen (no execution):

projectcli --language Rust --framework Actix --name my-api --dry-run

Extras flags:

• --devcontainer add a VS Code Dev Container
• --license force-add LICENSE (uses config defaults)
• --no-license never add LICENSE

Configuration

Save your preferences (like default package manager):

projectcli config

You can set defaults like:

• JS/TS package manager
• Author name (for LICENSE)
• Default license type (MIT/Apache2/ISC)

Project Config File (teams / automation)

ProjectCLI can also read a config file from the current directory:

• .projectclirc
• projectcli.config.json

Example:

{
  "packageManager": "pnpm",
  "author": "The Team",
  "license": "MIT",
  "ci": true,
  "docker": false,
  "devcontainer": true
}

Precedence:

1. CLI flags
2. Project config file
3. Global config (projectcli config → ~/.projectcli.json)

📦 Supported Generators (Partial List)

Language	Frameworks / Tools
JavaScript/TypeScript	React (Vite), Vue, Next.js, NestJS, Express, Astro, Svelte...
Rust	Binary, Library, Actix Web, Axum, Rocket, Taurus...
Python	Poetry, Setuptools, Django, Flask, FastAPI...
Go	Binary, Fiber, Gin, Chi, Echo...
PHP	Laravel, Symfony, Slim...
Java/Kotlin	Spring Boot, Gradle/Maven...
...and more	C#, Ruby, Swift, Dart

🧱 Architecture (for contributors)

ProjectCLI is intentionally simple: most “features” are data-driven.

• Registry entrypoint: src/registry.js (backwards-compatible import path for callers/tests).
• Built-in generators: src/registry_legacy.js.
• V3 registry wrapper (plugins/extensions): src/registry/index.js.
• Generators produce steps: each generator returns a list of steps (commands / mkdir / writeFile).
• Executor: steps are executed by src/run.js (it also prevents writing outside the project folder).
• Preflight: generators can declare required tools with check: ["cargo", "go", ...] and the wizard warns early.
• Remote templates: --template clones via src/remote.js, strips .git, then can apply Extras (CI/Docker/Devcontainer/License).

Adding a framework usually means:

1. Add an entry in src/registry.js with id, optional notes, optional check, and a commands() function.
2. Prefer non-interactive CLI args where possible (better for --yes/automation).
3. Run npm run lint and npm test.

🤝 Contributing

We love contributions! Whether it's adding a new framework to the registry or fixing a bug.

1. Fork it.
2. Create your feature branch (git checkout -b feature/new-framework).
3. Commit your changes (git commit -am 'Add support for X').
4. Push to the branch (git push origin feature/new-framework).
5. Create a new Pull Request.

See CONTRIBUTING.md for more details.

📝 License

MIT © Dawit Worku