> ## 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.

# CLI Commands

> Complete reference for all PPM command-line interface commands

# CLI Commands

PPM provides a comprehensive command-line interface for managing polyglot projects. This reference covers all available commands, their options, and usage examples.

## Global Options

These options are available for all PPM commands:

```bash theme={null}
ppm [GLOBAL_OPTIONS] <COMMAND> [COMMAND_OPTIONS]
```

| Option            | Short | Description               |
| ----------------- | ----- | ------------------------- |
| `--help`          | `-h`  | Show help information     |
| `--version`       | `-V`  | Show PPM version          |
| `--verbose`       | `-v`  | Enable verbose output     |
| `--quiet`         | `-q`  | Suppress non-error output |
| `--config <path>` | `-c`  | Use custom config file    |
| `--no-color`      |       | Disable colored output    |

## Core Commands

### `ppm init`

Initialize a new PPM project or convert existing project.

```bash theme={null}
ppm init [OPTIONS] [PROJECT_NAME]
```

**Arguments:**

* `PROJECT_NAME` - Name of the project (optional, uses current directory name)

**Options:**

| Option                   | Description                                  |
| ------------------------ | -------------------------------------------- |
| `--force`                | Overwrite existing project.toml              |
| `--template <name>`      | Use project template                         |
| `--js-manager <manager>` | JavaScript package manager (npm, yarn, pnpm) |
| `--python <version>`     | Python version to use                        |
| `--venv-dir <path>`      | Virtual environment directory                |
| `--no-js`                | Skip JavaScript setup                        |
| `--no-python`            | Skip Python setup                            |
| `--interactive`          | Interactive project setup                    |

**Examples:**

```bash theme={null}
# Initialize new project
ppm init my-app

# Initialize with specific managers
ppm init --js-manager yarn --python 3.11

# Convert existing project
ppm init --force

# Use template
ppm init --template react-flask

# Interactive setup
ppm init --interactive
```

### `ppm install`

Install project dependencies from project.toml.

```bash theme={null}
ppm install [OPTIONS] [PACKAGES...]
```

**Arguments:**

* `PACKAGES...` - Specific packages to install (optional)

**Options:**

| Option                | Description                           |
| --------------------- | ------------------------------------- |
| `--frozen`            | Install exact versions from lock file |
| `--no-lockfile`       | Don't generate/update lock file       |
| `--dev`               | Install development dependencies      |
| `--prod`              | Install only production dependencies  |
| `--env <environment>` | Use specific environment              |
| `--force`             | Force reinstall all packages          |
| `--offline`           | Don't access network (use cache only) |

**Examples:**

```bash theme={null}
# Install all dependencies
ppm install

# Install from lock file
ppm install --frozen

# Install only production dependencies
ppm install --prod

# Install development dependencies
ppm install --dev

# Install for specific environment
ppm install --env production

# Install specific packages
ppm install react flask
```

### `ppm add`

Add new dependencies to your project.

```bash theme={null}
ppm add [OPTIONS] <PACKAGES...>
```

**Arguments:**

* `PACKAGES...` - Packages to add (required)

**Options:**

| Option             | Description                      |
| ------------------ | -------------------------------- |
| `--dev`            | Add as development dependency    |
| `--optional`       | Add as optional dependency       |
| `--js`             | Force add as JavaScript package  |
| `--python`         | Force add as Python package      |
| `--version <spec>` | Specific version constraint      |
| `--no-install`     | Add to config without installing |

**Examples:**

```bash theme={null}
# Add packages (auto-detect language)
ppm add react axios flask numpy

# Add JavaScript packages explicitly
ppm add --js react @types/react

# Add Python packages explicitly  
ppm add --python flask sqlalchemy

# Add development dependencies
ppm add --dev eslint pytest black

# Add with specific versions
ppm add react@^18.0.0 flask@~3.0.0

# Add without installing
ppm add --no-install new-package
```

### `ppm remove`

Remove dependencies from your project.

```bash theme={null}
ppm remove [OPTIONS] <PACKAGES...>
```

**Arguments:**

* `PACKAGES...` - Packages to remove (required)

**Options:**

| Option           | Description                             |
| ---------------- | --------------------------------------- |
| `--dev`          | Remove from development dependencies    |
| `--js`           | Force remove as JavaScript package      |
| `--python`       | Force remove as Python package          |
| `--no-uninstall` | Remove from config without uninstalling |

**Examples:**

```bash theme={null}
# Remove packages
ppm remove react flask

# Remove development dependencies
ppm remove --dev eslint pytest

# Remove from config only
ppm remove --no-uninstall old-package
```

### `ppm run`

Execute scripts defined in project.toml or run commands.

```bash theme={null}
ppm run [OPTIONS] <SCRIPT|COMMAND> [ARGS...]
```

**Arguments:**

* `SCRIPT|COMMAND` - Script name or command to run
* `ARGS...` - Arguments to pass to the script/command

**Options:**

| Option                | Description                      |
| --------------------- | -------------------------------- |
| `--env <environment>` | Use specific environment         |
| `--parallel`          | Run multiple scripts in parallel |
| `--silent`            | Suppress script output           |

**Examples:**

```bash theme={null}
# Run defined scripts
ppm run dev
ppm run test
ppm run build

# Run with arguments
ppm run test --coverage

# Run commands directly
ppm run python app.py
ppm run node server.js

# Run in specific environment
ppm run --env production start

# Run multiple scripts in parallel
ppm run --parallel "npm run dev" "python manage.py runserver"
```

## Virtual Environment Commands

### `ppm venv`

Manage Python virtual environments.

```bash theme={null}
ppm venv <SUBCOMMAND> [OPTIONS]
```

#### Subcommands:

**`create`** - Create virtual environment

```bash theme={null}
ppm venv create [OPTIONS]

Options:
  --python <version>    Python version to use
  --name <name>         Environment name
  --system-site-packages Include system packages
```

**`activate`** - Show activation command

```bash theme={null}
ppm venv activate [OPTIONS]

Options:
  --show               Show command instead of executing
```

**`info`** - Show environment information

```bash theme={null}
ppm venv info [OPTIONS]

Options:
  --verbose            Show detailed information
```

**`list`** - List all environments

```bash theme={null}
ppm venv list
```

**`remove`** - Remove virtual environment

```bash theme={null}
ppm venv remove [OPTIONS]

Options:
  --force              Don't ask for confirmation
```

**`clean`** - Clean environment packages

```bash theme={null}
ppm venv clean
```

**`rebuild`** - Rebuild virtual environment

```bash theme={null}
ppm venv rebuild
```

## Information Commands

### `ppm list`

List installed packages.

```bash theme={null}
ppm list [OPTIONS]
```

**Options:**

| Option              | Description                      |
| ------------------- | -------------------------------- |
| `--js`              | Show only JavaScript packages    |
| `--python`          | Show only Python packages        |
| `--dev`             | Include development dependencies |
| `--outdated`        | Show only outdated packages      |
| `--format <format>` | Output format (table, json, csv) |

**Examples:**

```bash theme={null}
# List all packages
ppm list

# List only JavaScript packages
ppm list --js

# List outdated packages
ppm list --outdated

# Export as JSON
ppm list --format json
```

### `ppm tree`

Show dependency tree.

```bash theme={null}
ppm tree [OPTIONS] [PACKAGE]
```

**Arguments:**

* `PACKAGE` - Show tree for specific package (optional)

**Options:**

| Option        | Description                       |
| ------------- | --------------------------------- |
| `--js`        | Show only JavaScript dependencies |
| `--python`    | Show only Python dependencies     |
| `--depth <n>` | Maximum depth to show             |
| `--reverse`   | Show reverse dependencies         |

**Examples:**

```bash theme={null}
# Show full dependency tree
ppm tree

# Show tree for specific package
ppm tree react

# Limit depth
ppm tree --depth 2

# Show what depends on a package
ppm tree --reverse lodash
```

### `ppm outdated`

Check for outdated dependencies.

```bash theme={null}
ppm outdated [OPTIONS]
```

**Options:**

| Option              | Description                    |
| ------------------- | ------------------------------ |
| `--js`              | Check only JavaScript packages |
| `--python`          | Check only Python packages     |
| `--format <format>` | Output format (table, json)    |

### `ppm info`

Show package information.

```bash theme={null}
ppm info <PACKAGE> [OPTIONS]
```

**Arguments:**

* `PACKAGE` - Package name to show info for

**Options:**

| Option       | Description                |
| ------------ | -------------------------- |
| `--js`       | Look up JavaScript package |
| `--python`   | Look up Python package     |
| `--versions` | Show available versions    |

## Maintenance Commands

### `ppm update`

Update dependencies to latest versions.

```bash theme={null}
ppm update [OPTIONS] [PACKAGES...]
```

**Arguments:**

* `PACKAGES...` - Specific packages to update (optional)

**Options:**

| Option      | Description                                    |
| ----------- | ---------------------------------------------- |
| `--js`      | Update only JavaScript packages                |
| `--python`  | Update only Python packages                    |
| `--dev`     | Include development dependencies               |
| `--latest`  | Update to latest versions (ignore constraints) |
| `--dry-run` | Show what would be updated                     |

**Examples:**

```bash theme={null}
# Update all packages
ppm update

# Update specific packages
ppm update react flask

# Update to latest versions
ppm update --latest

# Show what would be updated
ppm update --dry-run
```

### `ppm audit`

Audit dependencies for security vulnerabilities.

```bash theme={null}
ppm audit [OPTIONS]
```

**Options:**

| Option               | Description                                        |
| -------------------- | -------------------------------------------------- |
| `--js`               | Audit only JavaScript packages                     |
| `--python`           | Audit only Python packages                         |
| `--fix`              | Automatically fix vulnerabilities                  |
| `--severity <level>` | Filter by severity (low, moderate, high, critical) |

### `ppm clean`

Clean package caches and temporary files.

```bash theme={null}
ppm clean [OPTIONS]
```

**Options:**

| Option    | Description                  |
| --------- | ---------------------------- |
| `--cache` | Clean package manager caches |
| `--deps`  | Clean installed dependencies |
| `--all`   | Clean everything             |
| `--force` | Don't ask for confirmation   |

## Import/Export Commands

### `ppm import`

Import from existing package files.

```bash theme={null}
ppm import [OPTIONS] [FILES...]
```

**Arguments:**

* `FILES...` - Files to import from (package.json, requirements.txt, etc.)

**Options:**

| Option          | Description                        |
| --------------- | ---------------------------------- |
| `--from <file>` | Import from specific file          |
| `--merge`       | Merge with existing project.toml   |
| `--dev`         | Import as development dependencies |

**Examples:**

```bash theme={null}
# Import from current directory
ppm import

# Import specific files
ppm import --from package.json --from requirements.txt

# Merge with existing config
ppm import --merge package.json
```

### `ppm export`

Export dependencies to other formats.

```bash theme={null}
ppm export [OPTIONS] <FORMAT>
```

**Arguments:**

* `FORMAT` - Export format (package.json, requirements.txt, etc.)

**Options:**

| Option            | Description                      |
| ----------------- | -------------------------------- |
| `--output <file>` | Output file path                 |
| `--dev`           | Include development dependencies |
| `--frozen`        | Export exact versions            |

**Examples:**

```bash theme={null}
# Export to package.json
ppm export package.json

# Export to requirements.txt
ppm export requirements.txt --frozen

# Export to custom file
ppm export package.json --output frontend/package.json
```

## Configuration Commands

### `ppm config`

Manage PPM configuration.

```bash theme={null}
ppm config <SUBCOMMAND> [OPTIONS]
```

#### Subcommands:

**`get`** - Get configuration value

```bash theme={null}
ppm config get <KEY>
```

**`set`** - Set configuration value

```bash theme={null}
ppm config set <KEY> <VALUE>
```

**`unset`** - Remove configuration value

```bash theme={null}
ppm config unset <KEY>
```

**`list`** - List all configuration

```bash theme={null}
ppm config list
```

**Examples:**

```bash theme={null}
# Get configuration
ppm config get python.version

# Set configuration
ppm config set python.version 3.11

# List all config
ppm config list
```

## Advanced Commands

### `ppm lock`

Manage lock files.

```bash theme={null}
ppm lock [OPTIONS]
```

**Options:**

| Option     | Description                         |
| ---------- | ----------------------------------- |
| `--update` | Update lock file without installing |
| `--check`  | Verify lock file is up to date      |

### `ppm verify`

Verify project integrity.

```bash theme={null}
ppm verify [OPTIONS]
```

**Options:**

| Option       | Description              |
| ------------ | ------------------------ |
| `--lockfile` | Verify against lock file |
| `--config`   | Verify configuration     |

### `ppm doctor`

Diagnose and fix common issues.

```bash theme={null}
ppm doctor [OPTIONS]
```

**Options:**

| Option      | Description               |
| ----------- | ------------------------- |
| `--fix`     | Automatically fix issues  |
| `--verbose` | Show detailed diagnostics |

## Exit Codes

PPM uses these exit codes:

| Code | Meaning             |
| ---- | ------------------- |
| 0    | Success             |
| 1    | General error       |
| 2    | Command not found   |
| 3    | Configuration error |
| 4    | Network error       |
| 5    | Permission error    |
| 6    | Package not found   |
| 7    | Version conflict    |

## Environment Variables

Control PPM behavior with environment variables:

| Variable             | Description             |
| -------------------- | ----------------------- |
| `PPM_CONFIG_FILE`    | Custom config file path |
| `PPM_CACHE_DIR`      | Custom cache directory  |
| `PPM_PYTHON_VERSION` | Default Python version  |
| `PPM_NO_COLOR`       | Disable colored output  |
| `PPM_VERBOSE`        | Enable verbose output   |

## Shell Completion

Enable shell completion for better CLI experience:

```bash theme={null}
# Bash
ppm completion bash > ~/.ppm-completion.bash
echo 'source ~/.ppm-completion.bash' >> ~/.bashrc

# Zsh
ppm completion zsh > ~/.ppm-completion.zsh
echo 'source ~/.ppm-completion.zsh' >> ~/.zshrc

# PowerShell
ppm completion powershell > $PROFILE
```

***

This reference covers all PPM CLI commands and options. For specific examples and use cases, see the [Quickstart Guide](/quickstart) and [Examples](/examples).