ProjectManager 🛠️

One command for all your projects. No matter the stack.

Stop wasting time remembering if it's gradle build, mvn package, cargo build, flutter build, or npm run build. Just use pm build.

🇪🇸 Leer en Español

---

📑 Table of Contents

• Why ProjectManager?
• Quick Win Example
• Features
• Requirements
• Installation
• Usage
• Supported Project Types
• Environment Variables
• Git Integration
• How It Compares
• Project Structure
• Configuration
• License Key
• Roadmap
• Contributing

---

🎯 Why ProjectManager?

The Problem You Face Daily

You're a developer with multiple projects:

# Project 1 (Gradle)
cd ~/projects/api-users
gradle build
# Wait... was it gradle or gradlew?

# Project 2 (Maven)
cd ~/projects/backend
mvn clean package
# Or was it mvn install?

# Project 3 (npm)
cd ~/projects/frontend
npm run build
# Need to set PORT=3000... or was it 3001?

# Check git status everywhere
cd ~/projects/api-users && git status
cd ~/projects/backend && git status
cd ~/projects/frontend && git status

Result:

• ⏰ 30+ minutes wasted daily navigating folders and looking up commands
• 🧠 Mental overhead remembering different build systems
• 😫 Context switching between 5+ different projects
• 🐛 Errors from using wrong commands or configurations

---

The ProjectManager Way

Same developer, same projects:

# From anywhere, any folder
pm build api-users
pm build backend
pm build frontend

# Run with correct config automatically
pm run api-users    # Uses PORT=3000
pm run backend      # Uses PORT=8080

# Check all git repos instantly
pm info api-users   # Branch: main, 2 modified
pm info backend     # Branch: dev, ✓ clean
pm info frontend    # Branch: feature/ui, 3 commits unpushed

Result:

• ✅ 5 seconds per command
• ✅ No thinking required
• ✅ Work from anywhere
• ✅ Never forget configurations

---

Real Impact

Time saved per week:

• Command lookups: ~2 hours
• Folder navigation: ~1 hour
• Configuration mistakes: ~30 min
• Git status checking: ~45 min

Total: ~4 hours/week = 16 hours/month = 2 full workdays

---

Who Benefits Most?

✅ Full-stack developers - Multiple technologies daily
✅ Team leads - Standardize commands across team
✅ Students - Learn new stacks without command confusion
✅ DevOps engineers - Manage multiple microservices
✅ Anyone with 3+ projects - Simplify your workflow

---

⚡ Quick Win Example

Before ProjectManager

Monday morning, 3 APIs to start:

cd ~/work/user-service
cat README.md  # Find instructions
export PORT=3001
export DB_HOST=localhost
mvn spring-boot:run

cd ~/work/product-service
npm install  # Just in case
PORT=3002 npm start

cd ~/work/order-service
# Was this Gradle or Maven?
ls  # Check for pom.xml or build.gradle
gradle bootRun --args='--server.port=3003'

Time: 10-15 minutes (if everything works)
Mental load: High
Error risk: Medium

---

After ProjectManager

Monday morning, same 3 APIs:

pm run user-service
pm run product-service
pm run order-service

Time: 15 seconds
Mental load: Zero
Error risk: None

Setup time: 5 minutes (one time)
Time saved: Every single day

---

✨ Features

• 🔍 Automatic detection - Detects Gradle, Maven, Node.js, .NET, Python, Rust, Go, pnpm, Bun, Yarn, Docker automatically
• 🎯 Unified commands - Same commands for all projects: pm build, pm run, pm test
• 📦 Centralized management - All projects in one place, accessible from anywhere
• ⚡ Fast execution - No folder navigation, instant command execution
• 💾 Persistence - Configuration saved in JSON, survives restarts
• 🌿 Git integration - See branch, status, and unpushed commits in pm info
• 🔧 Environment variables - Configure per-project variables (PORT, DEBUG, API_KEY, etc)
• 🩺 Runtime checker - Detects missing runtimes before execution, shows install instructions
• 🏥 pm doctor - Diagnose your environment: verify installed tools, validate project paths, and get A–F health scores
• 📊 Health scores - Project health grading (A/B/C/D/F) based on best practices (.gitignore, README, tests, CI, lockfile)
• 🔄 Auto-update - Check for updates on startup, update with pm update
• 🔃 Project refresh - Re-detect types and update commands with pm refresh, warns when projects are outdated
• ✏️ Rename & path update - Rename projects or update paths with pm rename, preserving all data
• 🎨 Custom commands - Add your own commands with pm commands add (tunnel, lint, deploy, etc.)
• 🛡️ Data safety - Atomic writes, automatic backup, and recovery from corrupted JSON
• 🔒 Safe execution - Directory validation before running commands, metacharacter warnings
• 🛡️ Robust auto-update - Download integrity validation, redirect loop protection, descriptive network error messages
• 🐳 Docker support - Detect Docker Compose projects, default commands (build, up, down, clean)
• 🪝 Pre-/post-command hooks - Run custom scripts before or after any command with pm hooks
• 🔤 Shell autocompletion - TAB completion for bash, zsh, fish, and PowerShell with pm completions
• 🔐 Security scan - Detect misconfigurations (Dockerfile root, exposed secrets, insecure URLs) with pm secure, auto-fix with --fix
• 🔍 Dependency audit - Scan dependencies for known vulnerabilities with pm audit using native tools (npm audit, cargo audit, govulncheck, pip-audit, dotnet)
• 📤 Export & Import - Migrate setups between machines with pm export and pm import, supports selective export and path validation
• 🔄 CI/CD detection - Detect GitHub Actions, GitLab CI, Jenkins, Travis CI, CircleCI with pm ci and in pm info
• 🧹 Linting & Formatting - Run linters with pm lint and formatters with pm fmt, auto-detects ESLint, Clippy, Prettier, gofmt, Ruff, and more
• 📦 Multi-project Workspaces - Detect monorepo modules with pm modules, multi-language detection, pm build --all and pm test --all
• 📂 Env File Detection - Discover .env files with pm env files, view masked contents with pm env show, switch environments with pm env switch
• 🔑 Secret Scanning - Detect hardcoded secrets (AWS keys, GitHub tokens, Slack tokens) in .env files, integrated in pm doctor and pm secure
• 🗄️ Database Migrations - Detect migration tools (Prisma, Alembic, Diesel, Flyway, Liquibase, SQLx) with pm migrate, run and check status
• 🔑 License Key System - Open Core model with pm license, RSA-SHA256 offline validation, Community/Pro branding (no feature restrictions)
• 📈 Performance Tracking - Auto-record build/test/run times, view history and trends with pm stats, per-project averages and summaries
• 🌐 Multi-platform - Works on Windows, Linux, and Mac

---

📋 Requirements

• Java 17 or higher (recommended: Java 21 LTS)
• Maven 3.6 or higher
• Git (optional, for repository information)

---

🚀 Installation

Quick start — download the latest release and run the installer:

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

# Linux/Mac
chmod +x scripts/install.sh && ./scripts/install.sh

📖 Full installation guide (step-by-step, build from source, troubleshooting, uninstall): INSTALL.md

---

💻 Usage

Available Commands

Command	Description
pm add <name> --path <path>	Register a new project
pm add <name> --path <path> --env "KEY=value,..."	Register with environment variables
pm list	List all projects
pm build <name>	Build a project
pm run <name>	Run a project
pm test <name>	Run tests
pm commands <name>	View available commands
pm commands <name> add <cmd> "<line>"	Add a custom command
pm commands <name> remove <cmd>	Remove a command
pm commands --all	View commands for all projects
pm info <name>	View detailed information (including Git status)
pm remove <name>	Remove project
pm env set <name> KEY=VALUE	Set environment variables
pm env get <name> KEY	Get a variable value
pm env list <name> [--show]	List variables (sensitive values masked)
pm env remove <name> KEY	Remove a variable
pm env clear <name>	Remove all variables
pm env files <name>	List .env files in project directory
pm env show <name> <file> [--show]	Show .env file contents (masked by default)
pm env switch <name> <env-name>	Copy .env.<env-name> to .env
pm hooks <name>	List hooks for a project
pm hooks <name> add <slot> "<script>"	Add a pre-/post-command hook
pm hooks <name> remove <slot> "<script>"	Remove a hook
pm hooks --all	List hooks for all projects
pm completions <shell>	Generate completion script (bash/zsh/fish/powershell)
pm rename <old> <new>	Rename a project
pm rename <name> --path <path>	Update project path
pm refresh <name>	Re-detect project type and update commands
pm refresh --all	Refresh all registered projects
pm update	Update to the latest version
pm doctor	Diagnose environment (runtimes, paths, health scores)
pm doctor --score	Show only health grades (A/B/C/D/F) per project
pm secure	Scan projects for security misconfigurations
pm secure --fix	Auto-fix .gitignore issues (add .env, *.pem, *.key entries)
pm audit	Audit dependencies for known vulnerabilities
pm ci [name]	Show CI/CD pipelines and dashboard URLs
pm lint [name]	Run linters on project(s)
pm fmt [name]	Run formatters on project(s)
pm modules [name]	Show workspace modules
pm migrate	List detected migration tools per project
pm migrate <name>	Run database migration (with confirmation)
pm migrate <name> status	Check migration status
pm build --all	Build all registered projects
pm test --all	Test all registered projects
pm export	Export all projects to a portable JSON file
pm export <names...> [--file <path>]	Export selected projects to a custom file
pm import <file>	Import projects from an exported JSON file
pm config telemetry [on|off]	Enable or disable anonymous telemetry
pm license [info]	Show current license status
pm license activate <key>	Activate a Pro license key
pm license deactivate	Remove license, revert to Community Edition
pm stats <name>	Show build/test/run time history for a project
pm stats --all	Show performance summary across all projects
pm help	Show help
pm version	Show version

Examples

# Register a project (automatic detection)
pm add my-api --path ~/projects/my-api

# Register with environment variables
pm add my-api --path ~/projects/my-api --env "PORT=8080,DEBUG=true,API_KEY=secret"

# List all projects
pm list

# Build any project
pm build my-api

# Run with environment variables (automatic)
pm run my-api

# View project info + Git status
pm info my-api

Example output:

Project Information
───────────────────

my-api (Maven)
  Path: /home/user/projects/my-api
  Modified: 5 minutes ago
  Commands: 5
  Environment Variables: 3

  Git:
    Branch: feature/new-endpoint
    Status: 2 modified, 1 untracked
    Unpushed: 3 commits

Commands for my-api (Maven)

  Default
  build  →  mvn package
  run    →  mvn exec:java
  test   →  mvn test
  clean  →  mvn clean

  Custom
  lint   →  mvn checkstyle:check

Environment Variables
  PORT    = 8080
  DEBUG   = true
  API_KEY = secret

---

🗂️ Supported Project Types

Type	Detection Files	Default Commands
Gradle	build.gradle, build.gradle.kts	build, run, test, clean
Maven	pom.xml	package, exec:java, test, clean
Rust	Cargo.toml	build, run, test, clean
Go	go.mod	build, run, test, clean
Flutter	pubspec.yaml	build, run, test, clean
pnpm	pnpm-lock.yaml	build, dev, test
Bun	bun.lockb, bun.lock	build, dev, test
Yarn	yarn.lock	build, start, test
Node.js	package.json (fallback)	build, start, test
.NET	*.csproj, *.fsproj	build, run, test
Python	requirements.txt, setup.py	(manual configuration)
Docker	docker-compose.yml, docker-compose.yaml	build, up, down, clean

Detection priority: Language types always take priority. When a project has both pom.xml and docker-compose.yml, it's detected as Maven (not Docker). Docker is only detected when no language-specific type is found. For JS projects, specific package managers (pnpm, Bun, Yarn) take priority over generic Node.js.

Can't find your stack? ProjectManager works with any project - just configure commands manually.

---

🔧 Environment Variables

What Are They For?

Stop setting environment variables manually every time. Configure once, use forever.

Common Use Cases

API with configurable port:

pm add my-api --path ~/my-api --env "PORT=8080,HOST=localhost"
pm run my-api  # Automatically uses PORT=8080

Project with API keys:

pm add backend --path ~/backend --env "API_KEY=abc123,DB_HOST=localhost,DEBUG=true"
pm run backend  # All variables available

Java project with JVM options:

pm add big-project --path ~/big-project --env "MAVEN_OPTS=-Xmx4G -XX:+UseG1GC"
pm build big-project  # Uses 4GB RAM automatically

Manage Variables Anytime

pm env set my-api PORT=8080,DEBUG=true     # Set variables
pm env get my-api PORT                     # Get a value
pm env list my-api                         # List (sensitive values masked)
pm env list my-api --show                  # List (all values revealed)
pm env remove my-api DEBUG                 # Remove a variable
pm env clear my-api                        # Remove all variables

How It Works

1. Register once with variables (or add them later with pm env set)
2. Variables saved in configuration
3. Automatically injected when you run pm build, pm run, or pm test
4. View anytime with pm info or pm env list

---

🌿 Git Integration

Know your repository status without leaving your current folder.

What you see in pm info:

• Current branch - Which branch you're working on
• Working tree status - Modified, staged, untracked files
• Unpushed commits - How many commits need to be pushed

Benefits:

• ✅ Check multiple repos instantly
• ✅ Never forget to commit/push
• ✅ See which branch you're on without git status

---

🔄 How It Compares

Task	Without ProjectManager	With ProjectManager
Build a project	cd folder && gradle build	pm build myproject
Run with config	cd folder && PORT=8080 mvn exec:java	pm run myproject
Check git status	cd folder && git status	pm info myproject
Switch projects	cd ../other && ...	pm build other
Remember commands	Check docs/README	pm commands myproject

vs Other Tools:

• Make/Task runners: Requires per-project setup, no cross-technology support
• Shell aliases: Limited functionality, manual per-project configuration
• IDE: Locked to one editor, no CLI workflow
• ProjectManager: ✅ Universal, ✅ Portable, ✅ 5-minute setup

---

📁 Project Structure

ProjectManager/
├── src/main/java/pm/
│   ├── ProjectManager.java       # Main class
│   ├── core/                     # Models (Project, CommandInfo)
│   ├── cli/                      # CLI interface
│   ├── detector/                 # Type detection
│   ├── executor/                 # Command execution
│   ├── storage/                  # JSON persistence
│   ├── workspace/                # Workspace/monorepo detection
│   ├── tracking/                 # Performance tracking (stats)
│   └── util/                     # Utilities (Git, Adapters)
├── scripts/
│   ├── install.ps1               # Windows installer
│   ├── install.sh                # Linux/Mac installer
│   └── INSTALL.md                # Installation guide
├── docs/
│   └── es/                       # Spanish documentation
│       ├── README.md
│       ├── User-Guide.md
│       ├── ROADMAP.md
│       └── SECURITY.md
├── User-Guide.md                 # Complete user guide (English)
├── ROADMAP.md                    # Future plans and ideas
├── SECURITY.md                   # Security policy
├── CONTRIBUTING.md               # Contribution guidelines
└── pom.xml

---

🛠️ Configuration

Projects are saved in:

• Windows: C:\Users\User\.projectmanager\projects.json
• Linux/Mac: ~/.projectmanager/projects.json

Manual editing supported (advanced users only)

---

📊 Telemetry

ProjectManager collects anonymous usage statistics to improve the tool. Telemetry is opt-in — disabled by default.

What is collected

• PM version, OS name/version, Java version
• Command name (e.g., build, test) — no arguments
• Number of registered projects — no project names or paths

What is NOT collected

• Project names, file paths, source code
• Environment variables, secrets, credentials
• Personal information, IP addresses, usernames

Control

pm config telemetry on       # Enable
pm config telemetry off      # Disable
pm config telemetry          # Check status

On first run, PM asks: Enable telemetry? (y/n) — default is no. Delete ~/.projectmanager/config.json to reset all preferences.

---

🔑 License Key

ProjectManager follows an Open Core model. By default, it runs as Community Edition — all features are fully available with no restrictions.

How it works

• The banner shows "Community Edition" or "Pro" based on your license status
• License keys are validated offline using RSA-SHA256 signatures (no server calls)
• License data is stored locally at ~/.projectmanager/license.json
• Branding only — no features are gated or restricted
• Each license allows 2 activations (e.g., desktop + laptop)
• Use pm license deactivate to free a slot and move the license to another machine

Commands

pm license                     # Show current license status
pm license info                # Same as above (shows edition, holder, activations allowed)
pm license activate <key>      # Activate a Pro license key
pm license deactivate          # Free this activation slot, revert to Community Edition

Changing machines? Run pm license deactivate on the old machine first, then pm license activate <key> on the new one.

---

🚧 Roadmap

✅ Completed

• Core — Project registration, auto-detection (12 types), unified commands, JSON persistence
• CLI — pm doctor, pm env, pm refresh, pm rename, pm update, pm commands add/remove
• Runtimes — Gradle, Maven, Node.js, .NET, Python, Rust, Go, pnpm, Bun, Yarn, Flutter, Docker
• Integrations — Git status, interactive TTY, multi-platform installers, GitHub Actions
• Security — pm secure scans for misconfigurations, --fix auto-remediates .gitignore issues
• Audit — pm audit checks dependencies for known vulnerabilities using native ecosystem tools
• Portability — pm export / pm import for migrating setups between machines or sharing team configs
• CI/CD — pm ci detects pipelines (GitHub Actions, GitLab CI, Jenkins, Travis, CircleCI) and shows dashboard URLs
• Lint & Format — pm lint / pm fmt auto-detect and run linters/formatters (ESLint, Prettier, Clippy, gofmt, Ruff, Black, Checkstyle, Spotless, and more)
• Workspaces — pm modules detects monorepo structures (Cargo, npm/pnpm/yarn, Gradle, Go), multi-language detection, pm build --all / pm test --all
• Environments — pm env files/show/switch for .env file discovery, secret scanning (AWS, GitHub, Slack tokens), pm migrate for database migration tools (Prisma, Alembic, Diesel, Flyway, Liquibase, SQLx)
• Telemetry — Opt-in anonymous usage analytics via PostHog, pm config telemetry on/off, privacy-first design
• License Key — Open Core model with pm license, RSA-SHA256 offline validation, Community/Pro branding (no feature restrictions)
• Performance Tracking — pm stats tracks build/test/run times automatically, shows averages, min/max, and history per project
• Reliability — Atomic writes, backup/recovery, directory validation, download integrity, 800+ tests

Latest release: v2.0.0 (Performance Tracking) — Full version history in ROADMAP.md

💡 Future Ideas

• Project groups (pm group create backend api-users product-service, pm run-group backend)

See ROADMAP.md for the full roadmap with detailed plans.

---

🐛 Found a Bug?

We take bugs seriously! If you encounter a problem:

1. Check existing issues: Open Issues
2. Report a new bug: Create Bug Report

What to include in your bug report:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• pm version output
• Operating system
• Error messages (if any)

Example:

Bug: pm build fails on Windows with spaces in path

Steps:
1. pm add myproject --path "C:\My Projects\test"
2. pm build myproject
3. Error: Path not found

Expected: Build succeeds
Actual: Error with path containing spaces

---

💡 Feature Requests

Have an idea to improve ProjectManager? We'd love to hear it!

Submit Feature Request

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

---

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3). See LICENSE for details.

Commercial licensing is available for organizations that require alternative terms. See COMMERCIAL.md for details or contact: legal@softdryzz.com

---

👤 Author

SoftDryzz

• GitHub: @SoftDryzz

📩 General	contact@softdryzz.com
🛡️ Security	security@softdryzz.com
⚖️ Licensing	legal@softdryzz.com
👤 Founder	cristo@softdryzz.com

---

⭐ If ProjectManager saves you time, give it a star on GitHub!

💬 Questions? Open an issue or check the User Guide