ppm init

Initialize a new PPM project with polyglot support

ppm init

Initialize a new PPM project in the current directory or create a new directory with a basic project.toml configuration file.

Synopsis

ppm init [options] [project-name]

Description

The ppm init command sets up a new polyglot project with PPM. It creates the essential project.toml configuration file and optionally sets up a basic project structure.

Arguments

• project-name (optional): Name of the new project. If provided, creates a new directory with this name.

Options

Option	Short	Description	Default
--name <name>	-n	Project name (overrides directory name)	Directory name
--version <version>	-v	Initial project version	"1.0.0"
--description <desc>	-d	Project description	""
--author <author>	-a	Project author	Git user.name
--license <license>	-l	Project license	"MIT"
--template <template>	-t	Project template to use	"basic"
--js		Include JavaScript/Node.js support	false
--python		Include Python support	false
--both		Include both JavaScript and Python	false
--interactive	-i	Interactive mode with prompts	false
--force	-f	Overwrite existing files	false
--help	-h	Show help information

Usage Examples

Basic Initialization

Initialize PPM in the current directory:

ppm init

Creates a basic project.toml file:

[project]
name = "my-project"
version = "1.0.0"
description = ""

[dependencies.js]

[dependencies.python]

[scripts]

Create New Project Directory

Create a new project in a new directory:

ppm init my-awesome-app
cd my-awesome-app

Interactive Mode

Use interactive mode to customize the project setup:

ppm init --interactive

This will prompt you for:

• Project name
• Version
• Description
• Author
• License
• Languages to include
• Template to use

Specify Project Details

Create a project with specific metadata:

ppm init my-app \
  --description "A full-stack polyglot application" \
  --author "John Doe" \
  --license "Apache-2.0" \
  --version "0.1.0"

Language-Specific Initialization

Initialize with specific language support:

# JavaScript only
ppm init frontend-app --js

# Python only  
ppm init ml-project --python

# Both languages
ppm init fullstack-app --both

Template-Based Initialization

Use a predefined template:

# Web application template
ppm init my-webapp --template web

# Data science template
ppm init data-project --template data-science

# Microservices template
ppm init services --template microservices

Available Templates

basic (Default)

Minimal setup with empty dependency sections:

[project]
name = "project-name"
version = "1.0.0"

[dependencies.js]
[dependencies.python]
[scripts]

web

Full-stack web application with React and Flask:

[project]
name = "project-name"
version = "1.0.0"

[dependencies.js]
react = "^18.2.0"
react-dom = "^18.2.0"
vite = "^5.0.0"

[dependencies.python]
flask = "^3.0.0"
flask-cors = "^4.0.0"

[scripts]
dev = "ppm run dev:parallel"
"dev:frontend" = "cd frontend && npm run dev"
"dev:backend" = "cd backend && python app.py"
"dev:parallel" = "ppm run dev:backend & ppm run dev:frontend"

data-science

Data science project with Jupyter and visualization:

[project]
name = "project-name"
version = "1.0.0"

[dependencies.js]
"@nivo/core" = "^0.84.0"
"@nivo/line" = "^0.84.0"
react = "^18.2.0"

[dependencies.python]
jupyter = "^1.0.0"
pandas = "^2.0.0"
numpy = "^1.24.0"
matplotlib = "^3.7.0"
seaborn = "^0.12.0"

[scripts]
notebook = "jupyter lab"
dashboard = "cd dashboard && npm start"

microservices

Microservices architecture template:

[project]
name = "project-name"
version = "1.0.0"

[dependencies.js]
express = "^4.18.0"
react = "^18.2.0"

[dependencies.python]
fastapi = "^0.104.0"
uvicorn = "^0.23.0"

[scripts]
dev = "ppm run dev:all"
"dev:frontend" = "cd frontend && npm start"
"dev:api" = "cd api && uvicorn main:app --reload"
"dev:auth" = "cd auth && node server.js"
"dev:all" = "ppm run dev:api & ppm run dev:auth & ppm run dev:frontend"

cli

Command-line tool template:

[project]
name = "project-name"
version = "1.0.0"

[dependencies.js]
commander = "^11.0.0"
inquirer = "^9.2.0"

[dependencies.python]
click = "^8.1.0"
rich = "^13.5.0"

[scripts]
build = "ppm run build:js && ppm run build:python"
"build:js" = "cd js && npm run build"
"build:python" = "cd python && python setup.py build"

Project Structure

Depending on the template and options, ppm init may create additional directories:

Web Template Structure

my-webapp/
├── project.toml
├── frontend/
│   ├── package.json
│   ├── vite.config.ts
│   ├── index.html
│   └── src/
│       ├── App.tsx
│       └── main.tsx
├── backend/
│   ├── app.py
│   └── requirements.txt
└── README.md

Data Science Template Structure

data-project/
├── project.toml
├── notebooks/
│   └── analysis.ipynb
├── dashboard/
│   ├── package.json
│   └── src/
│       └── App.jsx
├── data/
│   ├── raw/
│   └── processed/
└── scripts/
    └── preprocess.py

Configuration File Details

The generated project.toml includes:

Project Metadata

• name: Project name (required)
• version: Semantic version (required)
• description: Project description
• author: Project author
• license: License identifier

Dependencies

• dependencies.js: JavaScript/Node.js packages
• dependencies.python: Python packages
• dev-dependencies.js: JavaScript development dependencies
• dev-dependencies.python: Python development dependencies

Scripts

Common development scripts like dev, build, test, etc.

Post-Initialization Steps

After running ppm init, you’ll typically want to:

1. Install dependencies:

   ppm install
   

2. Review the configuration:

   cat project.toml
   

3. Start development:

   ppm run dev
   

4. Customize the setup: Edit project.toml to add or modify dependencies and scripts.

Interactive Mode Details

When using --interactive, PPM will prompt for:

1. Project Information

   • Project name
   • Version (with semantic versioning validation)
   • Description
   • Author (defaults to Git configuration)
   • License (with common license suggestions)
2. Language Selection

   • JavaScript/Node.js support
   • Python support
   • Both languages
3. Template Choice

   • Available templates based on language selection
   • Custom template options
4. Additional Options

   • Git repository initialization
   • README.md generation
   • License file creation

Common Use Cases

1. Quick Prototype

ppm init prototype --both --template basic
cd prototype
ppm install

2. Production Web App

ppm init my-startup --template web --interactive
cd my-startup
# Customize project.toml as needed
ppm install
ppm run dev

3. Data Science Project

ppm init research-analysis --template data-science
cd research-analysis
ppm install
ppm run notebook

4. Converting Existing Project

cd existing-project
ppm init --force --template web
# PPM will analyze existing package.json/requirements.txt
ppm install

Error Handling

Common Errors

Directory already exists

Error: Directory 'my-project' already exists

Solution: Use --force to overwrite or choose a different name:

ppm init my-project --force
# or
ppm init my-project-v2

Invalid project name

Error: Invalid project name 'my_project!'

Solution: Use alphanumeric characters and hyphens only:

ppm init my-project  # ✓ Valid
ppm init myproject   # ✓ Valid
ppm init my_project  # ✗ Invalid (underscore)

Permission denied

Error: Permission denied: cannot create directory

Solution: Check directory permissions or run with appropriate privileges:

sudo ppm init my-project  # Linux/macOS
# Or choose a directory you have write access to

Integration with Other Commands

After initialization, common next steps:

# Install all dependencies
ppm install

# Add new dependencies
ppm add react axios flask pandas

# Run development servers
ppm run dev

# See available scripts
ppm run --list

---

The ppm init command is your starting point for any polyglot project. It sets up the foundation for unified dependency management and development workflows.