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
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 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 and validate project paths
🔄 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
🌐 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

Option A: Download from Release (Recommended)

No need to compile. Just download and run.

Step 1. Go to GitHub Releases

Step 2. Download two things:

Source code (zip) — contains the install scripts
projectmanager-1.3.0.jar — the pre-built application

Step 3. Extract the ZIP. You will get a folder like ProjectManager-1.3.0/. Copy the downloaded JAR inside it:

ProjectManager-1.3.0/          ← extracted folder
├── projectmanager-1.3.0.jar   ← place the JAR here
├── scripts/
│   ├── install.ps1
│   └── install.sh
├── README.md
└── ...

Step 4. Open a terminal inside the ProjectManager-1.3.0/ folder and run the installer:

Windows (PowerShell): Right-click the folder → "Open in Terminal", then:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

⚠️ The -ExecutionPolicy Bypass flag is required because Windows blocks scripts downloaded from the internet. This is safe — the script only copies the JAR to %USERPROFILE%\.projectmanager\ and creates a pm.bat wrapper in %USERPROFILE%\bin\.

Linux/Mac:

chmod +x scripts/install.sh && ./scripts/install.sh

Step 5. Close and reopen your terminal, then verify:

pm version

After installation, you can delete the downloaded ZIP and extracted folder. The JAR is copied to a permanent location during install.

Option B: Build from Source

Requires Java 17+ and Maven 3.6+.

# 1. Clone repository
git clone https://github.com/SoftDryzz/ProjectManager.git
cd ProjectManager

# 2. Compile
mvn clean package

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

# 3. Install (Linux/Mac)
chmod +x scripts/install.sh && ./scripts/install.sh

# 4. Verify
pm version

Setup time: 5 minutes Benefits: Forever

💻 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 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 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)
`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: 4
  Environment Variables: 3

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

Available Commands
  build  →  mvn package
  run    →  mvn exec:java
  test   →  mvn test
  clean  →  mvn clean

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)

Detection priority: When a project has both package.json and a lock file (pnpm-lock.yaml, bun.lockb, yarn.lock), the specific package manager is detected instead of 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

Register once with variables (or add them later with pm env set)
Variables saved in configuration
Automatically injected when you run pm build, pm run, or pm test
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
│   └── util/                     # Utilities (Git, Adapters)
├── scripts/
│   ├── install.ps1               # Windows installer
│   ├── install.sh                # Linux/Mac installer
│   └── INSTALL.md                # Installation guide
├── User-Guide.md                 # Complete user guide (English)
├── User-Guide_ES.md              # Complete user guide (Spanish)
├── ROADMAP.md                    # Future plans and ideas
├── 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)

🚧 Roadmap

✅ Completed

🔨 Planned (Priority Order)

Command aliases for long project names
Pre- / post-command hooks
scan command to detect @Command annotations

💡 Future Ideas

pm run-all / pm build-all - Execute commands across all projects
Project groups (pm group create backend api-users product-service, pm run-group backend)
Shell autocompletion (bash/zsh/PowerShell tab completion)
Docker support (detect Dockerfile/docker-compose, manage services)
Multi-ecosystem installers (npm, Cargo, Homebrew, Scoop, etc.)

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

🐛 Found a Bug?

We take bugs seriously! If you encounter a problem:

Check existing issues: Open Issues
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:

Fork the project
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

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

💬 Questions? Open an issue or check the User Guide

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.github		.github
.idea		.idea
docs/javadoc		docs/javadoc
scripts		scripts
src		src
.gitignore		.gitignore
COMMERCIAL.md		COMMERCIAL.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README_ES.md		README_ES.md
ROADMAP.md		ROADMAP.md
User-Guide.md		User-Guide.md
User-Guide_ES.md		User-Guide_ES.md
dependency-reduced-pom.xml		dependency-reduced-pom.xml
pom.xml		pom.xml

License

SoftDryzz/ProjectManager

Folders and files

Latest commit

History

Repository files navigation