> ## Documentation Index
> Fetch the complete documentation index at: https://kaiser.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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:

```bash theme={null}
ppm init
```

Creates a basic `project.toml` file:

```toml theme={null}
[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:

```bash theme={null}
ppm init my-awesome-app
cd my-awesome-app
```

### Interactive Mode

Use interactive mode to customize the project setup:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```toml theme={null}
[project]
name = "project-name"
version = "1.0.0"

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

### `web`

Full-stack web application with React and Flask:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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**:
   ```bash theme={null}
   ppm install
   ```

2. **Review the configuration**:
   ```bash theme={null}
   cat project.toml
   ```

3. **Start development**:
   ```bash theme={null}
   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:

<Steps>
  <Step title="Project Information">
    * Project name
    * Version (with semantic versioning validation)
    * Description
    * Author (defaults to Git configuration)
    * License (with common license suggestions)
  </Step>

  <Step title="Language Selection">
    * JavaScript/Node.js support
    * Python support
    * Both languages
  </Step>

  <Step title="Template Choice">
    * Available templates based on language selection
    * Custom template options
  </Step>

  <Step title="Additional Options">
    * Git repository initialization
    * README.md generation
    * License file creation
  </Step>
</Steps>

## Common Use Cases

### 1. Quick Prototype

```bash theme={null}
ppm init prototype --both --template basic
cd prototype
ppm install
```

### 2. Production Web App

```bash theme={null}
ppm init my-startup --template web --interactive
cd my-startup
# Customize project.toml as needed
ppm install
ppm run dev
```

### 3. Data Science Project

```bash theme={null}
ppm init research-analysis --template data-science
cd research-analysis
ppm install
ppm run notebook
```

### 4. Converting Existing Project

```bash theme={null}
cd existing-project
ppm init --force --template web
# PPM will analyze existing package.json/requirements.txt
ppm install
```

## Error Handling

### Common Errors

<AccordionGroup>
  <Accordion title="Directory already exists">
    **Error**: `Directory 'my-project' already exists`

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

    ```bash theme={null}
    ppm init my-project --force
    # or
    ppm init my-project-v2
    ```
  </Accordion>

  <Accordion title="Invalid project name">
    **Error**: `Invalid project name 'my_project!'`

    **Solution**: Use alphanumeric characters and hyphens only:

    ```bash theme={null}
    ppm init my-project  # ✓ Valid
    ppm init myproject   # ✓ Valid
    ppm init my_project  # ✗ Invalid (underscore)
    ```
  </Accordion>

  <Accordion title="Permission denied">
    **Error**: `Permission denied: cannot create directory`

    **Solution**: Check directory permissions or run with appropriate privileges:

    ```bash theme={null}
    sudo ppm init my-project  # Linux/macOS
    # Or choose a directory you have write access to
    ```
  </Accordion>
</AccordionGroup>

## Integration with Other Commands

After initialization, common next steps:

```bash theme={null}
# 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.