# gpm init

Initialize a new Unity Package Manager (UPM) compatible package.

## Usage

```bash
gpm init [flags]
```

## Flags

| Flag                   | Description                          | Default  |
| ---------------------- | ------------------------------------ | -------- |
| `--name <name>`        | Package name (reverse DNS format)    | Prompted |
| `--version <version>`  | Package version                      | `1.0.0`  |
| `--description <desc>` | Package description                  | Prompted |
| `--license <license>`  | Package license                      | `MIT`    |
| `--unity <version>`    | Minimum Unity version                | `2021.3` |
| `--yes`                | Accept all defaults and skip prompts | `false`  |
| `--json`               | Output results in JSON format        | `false`  |

## Description

The `gpm init` command creates a new Unity Package Manager (UPM) compatible package by generating a `package.json` file with all necessary fields for Unity Package Manager compatibility and GPM registry publishing.

### Package Structure Created

* **package.json**: Package metadata and configuration
* **README.md**: Package documentation template
* **LICENSE**: Package license file
* **Runtime/**: Runtime scripts directory
* **Editor/**: Editor scripts directory
* **Tests/**: Test scripts directory

## Examples

### Interactive Initialization

```bash
# Initialize with prompts
gpm init

# Interactive prompts:
# Package name: com.company.mypackage
# Description: My awesome Unity package
# Author: John Doe
# License: MIT
# Unity version: 2021.3
```

### Non-Interactive Initialization

```bash
# Initialize with all defaults
gpm init --yes

# Initialize with specific values
gpm init --name com.company.mypackage --description "My package" --yes
```

### Advanced Initialization

```bash
# Initialize with custom values
gpm init --name com.company.mypackage --version 1.0.0 --description "My package" --license MIT --unity 2022.3

# Initialize with JSON output
gpm init --yes --json
```

## Package.json Generation

### Generated package.json

```json
{
  "name": "com.company.mypackage",
  "version": "1.0.0",
  "description": "My awesome Unity package",
  "displayName": "My Package",
  "author": {
    "name": "John Doe",
    "email": "john@company.com"
  },
  "license": "MIT",
  "unity": "2021.3",
  "keywords": [
    "unity",
    "package",
    "gpm"
  ],
  "dependencies": {},
  "repository": {
    "type": "git",
    "url": "https://github.com/company/mypackage.git"
  },
  "bugs": {
    "url": "https://github.com/company/mypackage/issues"
  },
  "homepage": "https://github.com/company/mypackage#readme"
}
```

### Package Name Validation

The package name must follow Unity UPM reverse-DNS format:

* **Format**: `com.company.package`
* **Validation**: `^(?:[a-z0-9]+(?:-[a-z0-9]+)*\.)+[a-z0-9]+(?:-[a-z0-9]+)*$`
* **Examples**: `com.unity.analytics`, `com.company.mypackage`

## Directory Structure

### Created Directories

```
mypackage/
├── package.json
├── README.md
├── LICENSE
├── Runtime/
│   └── MyPackage/
│       └── MyPackage.cs
├── Editor/
│   └── MyPackage/
│       └── MyPackageEditor.cs
└── Tests/
    └── Runtime/
        └── MyPackageTests.cs
```

### Directory Purposes

* **Runtime/**: Contains runtime scripts and assets
* **Editor/**: Contains editor-only scripts and assets
* **Tests/**: Contains test scripts and assets

## Output

### Human Format (Default)

```
Package Initialized Successfully
─────────────────────────────────
Package:  com.company.mypackage
Version:  1.0.0
License:  MIT
Unity:    2021.3
─────────────────────────────────
Package com.company.mypackage initialized successfully
```

### JSON Format (`--json`)

```json
{
  "success": true,
  "package": "com.company.mypackage",
  "version": "1.0.0",
  "license": "MIT",
  "unity": "2021.3",
  "message": "Package com.company.mypackage initialized successfully"
}
```

## Package Configuration

### Required Fields

* **name**: Package identifier (reverse-DNS format)
* **version**: Package version (semantic versioning)
* **description**: Package description
* **author**: Package author information
* **license**: Package license
* **unity**: Minimum Unity version

### Optional Fields

* **displayName**: Human-readable package name
* **keywords**: Package keywords for search
* **dependencies**: Package dependencies
* **repository**: Git repository information
* **bugs**: Bug tracker URL
* **homepage**: Package homepage URL

## Package Templates

### Basic Package

```bash
# Create basic package
gpm init --name com.company.basic --yes
```

### Advanced Package

```bash
# Create advanced package with custom values
gpm init --name com.company.advanced --version 1.0.0 --description "Advanced package" --license MIT --unity 2022.3
```

### Template Customization

```bash
# Initialize and customize
gpm init --name com.company.mypackage
# Edit package.json
# Add custom files
# Customize README.md
```

## Error Handling

### Common Errors

* **Invalid package name**: `invalid package name: must use reverse-DNS format`
* **Package already exists**: `package.json already exists in directory`
* **Invalid Unity version**: `invalid Unity version: must be valid version`
* **File creation error**: `failed to create package files`

### Troubleshooting

1. **Invalid package name**: Use reverse-DNS format (e.g., `com.company.package`)
2. **Package already exists**: Remove existing `package.json` or use different directory
3. **Invalid Unity version**: Use valid Unity version (e.g., `2021.3`, `2022.3`)
4. **File creation error**: Check directory permissions and disk space

## Best Practices

### Package Naming

```bash
# Use descriptive package names
gpm init --name com.company.analytics-sdk

# Use consistent naming convention
gpm init --name com.company.ui-framework
gpm init --name com.company.networking-utils
```

### Version Management

```bash
# Start with version 1.0.0
gpm init --name com.company.mypackage --version 1.0.0

# Use semantic versioning
gpm version patch  # 1.0.0 → 1.0.1
gpm version minor  # 1.0.0 → 1.1.0
gpm version major  # 1.0.0 → 2.0.0
```

### Documentation

```bash
# Initialize with good description
gpm init --name com.company.mypackage --description "A comprehensive Unity package for game analytics and player insights"

# Customize README.md
# Add usage examples
# Document API
# Add screenshots
```

## Integration with Publishing

### Package Development Workflow

```bash
# 1. Initialize package
gpm init --name com.company.mypackage

# 2. Develop package
# Add source code
# Add tests
# Update documentation

# 3. Pack package
gpm pack

# 4. Publish package
gpm publish --access=scoped
```

### Version Control

```bash
# Initialize package
gpm init --name com.company.mypackage

# Initialize git repository
git init
git add .
git commit -m "Initial package structure"

# Add remote repository
git remote add origin https://github.com/company/mypackage.git
git push -u origin main
```

## Related Commands

* [`gpm pack`](/cli-reference/cli/publishing/pack.md) - Create package tarball
* [`gpm publish`](/cli-reference/cli/publishing/publish.md) - Publish package to registry
* [`gpm version`](/cli-reference/cli/utilities/version.md) - Manage package versions

## See Also

* [Project Management](/cli-reference/cli/project.md)
* [Package Guidelines](https://github.com/gpm-sh/docs/blob/main/packages/README.md)
* [Unity Package Manager](https://github.com/gpm-sh/docs/blob/main/engines/unity.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gpm.sh/cli-reference/cli/project/init.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.