### Complete pnpm action configuration example

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

A comprehensive example showing various configuration options for the pnpm action setup, including version, destination, caching, package file, and run install commands.

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v6
        id: pnpm-setup
        with:
          version: 9.0.0
          dest: ~/.pnpm-home
          cache: true
          cache_dependency_path: |
            pnpm-lock.yaml
            packages/*/pnpm-lock.yaml
          package_json_file: package.json
          run_install: |
            - recursive: true
              args: [--strict-peer-dependencies]
            - cwd: packages/web
              args: [--frozen-lockfile]
      
      - name: Use pnpm outputs
        run: |
          echo "pnpm binary: ${{ steps.pnpm-setup.outputs.bin_dest }}/pnpm"
          echo "cache status: ${{ steps.pnpm-setup.outputs.cache-hit }}"
          pnpm --version
```

--------------------------------

### pnpm install command examples

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-install.md

Illustrates how different configuration options translate into pnpm install commands.

```bash
pnpm install
```

```bash
pnpm recursive install
```

```bash
pnpm install --frozen-lockfile
```

```bash
pnpm recursive install --strict-peer-dependencies
```

```bash
pnpm install --frozen-lockfile (in apps/web)
```

--------------------------------

### Examples of Controlling pnpm Install

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Illustrates various configurations for running 'pnpm install', from skipping it entirely to executing complex recursive or targeted installations with specific arguments.

```yaml
# No installation
run_install: false

# Simple recursive install
run_install: true

# Single install with options
run_install: |
  args: [--frozen-lockfile, --strict-peer-dependencies]

# Multiple install commands
run_install: |
  - recursive: true
    args: [--strict-peer-dependencies]
  - cwd: apps/web
    args: [--frozen-lockfile]
  - cwd: apps/api
    args: [--frozen-lockfile, --ignore-scripts]
```

--------------------------------

### Basic pnpm Setup

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/index.md

Installs a specified version of pnpm. Use this for straightforward setup without caching or installation steps.

```yaml
uses: pnpm/action-setup@v6
  with:
    version: 9
```

--------------------------------

### Example: Setting pnpm Action Outputs in TypeScript

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/outputs.md

Demonstrates how to use `getInputs`, `install`, and `setOutputs` to configure and set GitHub Actions outputs after a successful pnpm installation.

```typescript
import getInputs from '@pnpm/action-setup/inputs'
import install from '@pnpm/action-setup/install-pnpm'
import setOutputs from '@pnpm/action-setup/outputs'

const inputs = getInputs()
const binDest = await install(inputs)
if (binDest) {
  setOutputs(inputs, binDest)
  // Now ${{ steps.setup-pnpm.outputs.dest }} and 
  // ${{ steps.setup-pnpm.outputs.bin_dest }} are available
}
```

--------------------------------

### Example pnpm install failures

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-install.md

Shows example log outputs for failed pnpm install commands, including the command, working directory, and exit status.

```bash
Command pnpm recursive install (cwd: undefined) exits with status 1
```

```bash
Command pnpm install --frozen-lockfile (cwd: apps/web) exits with status 2
```

--------------------------------

### Install pnpm using install()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/install-pnpm.md

Use the `install()` function as the main entry point for installing pnpm. It wraps `runSelfInstaller()` with error handling and GitHub Actions UI grouping. It returns the binary destination path on success or undefined on failure.

```typescript
import install from '@pnpm/action-setup/install-pnpm'
import getInputs from '@pnpm/action-setup/inputs'

const inputs = getInputs()
const binDest = await install(inputs)
if (binDest) {
  console.log(`pnpm available at: ${binDest}`)
} else {
  console.error('pnpm installation failed')
}
```

--------------------------------

### Examples of Installation Destination

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Shows different ways to specify the destination directory for pnpm, including relative paths, absolute paths, and home directory subdirectories.

```yaml
dest: "~/.pnpm"                    # Home directory subdirectory
dest: "/opt/pnpm"                  # Absolute path
dest: "./tools/pnpm"               # Relative path (relative to workspace)
```

--------------------------------

### Installation Flow Diagram

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/module-structure.md

Illustrates the sequence of operations during the installation process, from initial inputs to running pnpm install.

```text
Inputs
    ↓
install(inputs)
    ├── runSelfInstaller(inputs)
    │   ├── readTargetVersion() → version
    │   ├── getSystemNodeVersion() → detect standalone mode
    │   ├── npm ci (bootstrap pnpm)
    │   ├── pnpm self-update <version>
    │   └── Setup PATH and PNPM_HOME
    │
    └── Return: SelfInstallerResult { exitCode, binDest }
            ↓
        setOutputs(inputs, binDest) → dest, bin_dest
        restoreCache(inputs) → cache-hit output
        runPnpmInstall(inputs) → execute each RunInstall
```

--------------------------------

### pnpm Setup with Caching and Installation

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/index.md

Configures pnpm with caching enabled and automatically runs the installation process. This is useful for CI environments to speed up builds.

```yaml
uses: pnpm/action-setup@v6
  with:
    version: 9
    cache: true
    run_install: true
```

--------------------------------

### Standalone mode examples

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Examples demonstrating how to force standalone mode or use regular pnpm.

```yaml
standalone: true    # Force standalone mode
standalone: false   # Use regular pnpm (may fail on old Node.js)
```

--------------------------------

### YAML: Using pnpm Action Outputs in a Workflow

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/outputs.md

Shows how to reference the `dest` and `bin_dest` outputs from the pnpm setup step in subsequent workflow steps to display installation paths and execute pnpm.

```yaml
- name: Setup pnpm
  id: setup-pnpm
  uses: pnpm/action-setup@v6
  with:
    version: 9

- name: Use pnpm outputs
  run: |
    echo "pnpm stored at: ${{ steps.setup-pnpm.outputs.dest }}"
    echo "pnpm bin at: ${{ steps.setup-pnpm.outputs.bin_dest }}"
    # Both of these work since bin_dest is in PATH
    pnpm --version
    ${{ steps.setup-pnpm.outputs.bin_dest }}/pnpm --version
```

--------------------------------

### install()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/install-pnpm.md

Main entry point for installing pnpm. It calls the self-installer and handles potential errors, returning the path to the pnpm binary directory on success or undefined on failure.

```APIDOC
## install()

### Description
Main entry point for installing pnpm. Calls the self-installer and handles errors.

### Method
async

### Signature
install(inputs: Inputs): Promise<string | undefined>

### Parameters
#### Path Parameters
- **inputs** (Inputs) - Required - Configuration object containing version, destination, and other settings.

### Returns
`string | undefined` — Path to the pnpm binary directory (e.g., `/path/to/dest/node_modules/.bin`), or `undefined` if installation failed.

### Description
Wraps the `runSelfInstaller()` function with error handling and GitHub Actions UI grouping. On exit code 0, returns the binary destination path. On non-zero exit, logs failure message and returns `undefined`.

### Example
```typescript
import install from '@pnpm/action-setup/install-pnpm'
import getInputs from '@pnpm/action-setup/inputs'

const inputs = getInputs()
const binDest = await install(inputs)
if (binDest) {
  console.log(`pnpm available at: ${binDest}`)
} else {
  console.error('pnpm installation failed')
}
```
```

--------------------------------

### Install pnpm and npm packages

Source: https://github.com/pnpm/action-setup/blob/master/README.md

Installs pnpm and then runs 'pnpm install' with specified options. Supports recursive installation and global package installation.

```yaml
on:
  - push
  - pull_request

jobs:
  install:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - uses: pnpm/action-setup@v6
        with:
          version: 10
          run_install: |
            - recursive: true
              args: [--strict-peer-dependencies]
            - args: [--global, gulp, prettier, typescript]
```

--------------------------------

### Examples of Cache Dependency Path

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Demonstrates specifying a single lockfile or multiple lockfiles for cache key generation, useful in monorepo setups.

```yaml
# Single lockfile
cache_dependency_path: pnpm-lock.yaml

# Multiple lockfiles (monorepo)
cache_dependency_path: |
  pnpm-lock.yaml
  packages/*/pnpm-lock.yaml

# Explicit paths
cache_dependency_path: |
  one/pnpm-lock.yaml
  two/pnpm-lock.yaml
```

--------------------------------

### Monorepo Setup with Caching and Custom Install Paths

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/index.md

Sets up pnpm for a monorepo, enabling caching and specifying custom installation configurations for different workspaces. This allows for fine-grained control over dependency installation in complex projects.

```yaml
uses: pnpm/action-setup@v6
  with:
    version: 9
    cache: true
    cache_dependency_path: |
      pnpm-lock.yaml
      packages/*/pnpm-lock.yaml
    run_install: |
      - recursive: true
      - cwd: apps/web
        args: [--frozen-lockfile]
      - cwd: apps/api
        args: [--frozen-lockfile]
```

--------------------------------

### YAML: Referencing pnpm Installation Paths

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/outputs.md

Illustrates how to access and display the `dest` and `bin_dest` output variables from a pnpm setup step within a GitHub Actions workflow.

```yaml
- name: Setup pnpm
  id: pnpm
  uses: pnpm/action-setup@v6
  with:
    version: 9

- name: Show installation paths
  run: |
    echo "Installation root: ${{ steps.pnpm.outputs.dest }}"
    echo "Binary directory: ${{ steps.pnpm.outputs.bin_dest }}"
```

--------------------------------

### Example Usage of pruneStore

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-store.md

Demonstrates how to import and use the pruneStore function with inputs obtained from getInputs. This example shows the command that will be executed.

```typescript
import getInputs from '@pnpm/action-setup/inputs'
import { pruneStore } from '@pnpm/action-setup/pnpm-store-prune'

const inputs = getInputs()
pruneStore(inputs)
// Runs: pnpm store prune
```

--------------------------------

### Basic pnpm installation in GitHub Actions

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-install.md

A basic GitHub Actions workflow snippet to set up pnpm and run a basic installation.

```yaml
- uses: pnpm/action-setup@v6
  with:
    version: 9
    run_install: true
```

--------------------------------

### Verify pnpm Installation Outputs

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

After running the pnpm/action-setup action, check its outputs to confirm the installation destination, binary destination, and cache hit status. This helps in understanding the action's execution results.

```bash
- uses: pnpm/action-setup@v6
  id: pnpm-setup
  with:
    version: 9

- name: Check outputs
  run: |
    echo "dest=${{ steps.pnpm-setup.outputs.dest }}"
    echo "bin_dest=${{ steps.pnpm-setup.outputs.bin_dest }}"
    echo "cache-hit=${{ steps.pnpm-setup.outputs.cache-hit }}"
```

--------------------------------

### GitHub Actions Workflow with pnpm Setup and Cache

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-store.md

A sample GitHub Actions workflow demonstrating the setup of pnpm with caching enabled and the 'run_install' option. The post-action phase automatically includes 'pnpm store prune'.

```yaml
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v6
        with:
          version: 9
          cache: true
          run_install: true
      
      - name: Run tests
        run: pnpm test

# Post-action automatically runs:
# 1. pnpm store prune (cleanup)
# 2. Cache save (if cache key changed)
```

--------------------------------

### Example Usage of runPnpmInstall

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-install.md

Demonstrates how to use the `runPnpmInstall` function with a configured `inputs` object. Shows the resulting pnpm commands executed.

```typescript
import getInputs from '@pnpm/action-setup/inputs'
import { runPnpmInstall } from '@pnpm/action-setup/pnpm-install'

const inputs = getInputs()
// With runInstall configured as:
// - recursive: true
//   args: [--strict-peer-dependencies]
// - cwd: apps/web
//   args: [--frozen-lockfile]

runPnpmInstall(inputs)
// Executes:
// 1. pnpm recursive install --strict-peer-dependencies
// 2. pnpm install --frozen-lockfile (in cwd: apps/web)
```

--------------------------------

### Main Action Phase Execution

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/module-structure.md

This function handles the primary execution of the GitHub Action, including parsing inputs, installing pnpm, setting outputs, restoring cache, and running pnpm install. It's executed when the action starts.

```typescript
async function runMain() {
  const inputs = getInputs()              // Parse inputs
  saveState('inputs', inputs)             // Save for post-action
  saveState('is_post', 'true')            // Mark post-action
  
  const binDest = await installPnpm(inputs)     // Install pnpm
  if (binDest === undefined) return       // Exit if failed
  console.log('Installation Completed!')
  setOutputs(inputs, binDest)             // Set action outputs
  
  await restoreCache(inputs)              // Restore store from cache
  
  pnpmInstall(inputs)                     // Run pnpm install
}
```

--------------------------------

### RunInstall Type Definition

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/types.md

Defines the configuration for a single pnpm install or recursive install command. Specify recursive behavior, working directory, and additional arguments.

```typescript
type RunInstall = {
  readonly recursive?: boolean
  readonly cwd?: string
  readonly args?: string[]
}
```

--------------------------------

### Use cache to reduce installation time

Source: https://github.com/pnpm/action-setup/blob/master/README.md

Enables caching for the pnpm store directory to speed up subsequent installations. Requires 'pnpm install' to be run separately after the action.

```yaml
on:
  - push
  - pull_request

jobs:
  cache-and-install:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - uses: pnpm/action-setup@v6
        name: Install pnpm
        with:
          version: 10
          cache: true

      - name: Install dependencies
        run: pnpm install
```

--------------------------------

### runPnpmInstall()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-install.md

Executes all configured pnpm install commands based on the provided inputs. It iterates through the 'runInstall' array in the inputs, constructing and executing each pnpm command with appropriate options like recursion, working directory, and custom arguments. Errors are logged, but execution continues to the next command.

```APIDOC
## runPnpmInstall()

### Description
Executes all configured pnpm install commands. This function iterates through the `inputs.runInstall` array and runs each configuration as a separate `pnpm install` or `pnpm recursive install` command. Output is visible in action logs due to `stdio: 'inherit'`.

### Function Signature
```typescript
function runPnpmInstall(inputs: Inputs): void
```

### Parameters
#### Path Parameters
- **inputs** (Inputs) - Required - Configuration object containing `runInstall` array.

### Returns
`void`

### Behavior Details
- **Recursion**: If `options.recursive` is true, prepends `recursive` to the pnpm command.
- **Working Directory**: If `options.cwd` is set, runs the command in that directory.
- **Arguments**: Appends all `options.args` to the command.
- **Error Handling**: If an error occurs or a command returns a non-zero exit code, it logs the failure and continues to the next install command without throwing an error.

### Example
```typescript
import getInputs from '@pnpm/action-setup/inputs'
import { runPnpmInstall } from '@pnpm/action-setup/pnpm-install'

const inputs = getInputs()
// Assuming inputs.runInstall is configured with recursive and args, or cwd and args
runPnpmInstall(inputs)
```

### Command Construction Logic
Commands are built by combining:
1. Base command: `["install"]`
2. If `recursive: true`: prepend `"recursive"` → `["recursive", "install"]`
3. If `args` provided: append all args → `["recursive", "install", ...args]`
4. Command prefix: `pnpm`

**Examples:**
- `{}` → `pnpm install`
- `{ recursive: true }` → `pnpm recursive install`
- `{ args: ["--frozen-lockfile"] }` → `pnpm install --frozen-lockfile`
- `{ recursive: true, args: ["--strict-peer-dependencies"] }` → `pnpm recursive install --strict-peer-dependencies`
- `{ cwd: "apps/web", args: ["--frozen-lockfile"] }` → `pnpm install --frozen-lockfile` (in `apps/web`)

### Error Handling Details
When a command fails:
1. The command string and working directory are logged.
2. If `spawnSync` encounters an error (e.g., command not found), it's logged via `setFailed()`.
3. If the command returns a non-zero exit status, a formatted error message is logged via `setFailed()`.
4. Execution continues to the next install command in the array (no throwing).
5. All failures are captured and reported to GitHub Actions.

**Example Failure Logs:**
```
Command pnpm recursive install (cwd: undefined) exits with status 1
Command pnpm install --frozen-lockfile (cwd: apps/web) exits with status 2
```

### Environment Variables Inherited
The spawned pnpm process inherits `process.env`, including:
- `PNPM_HOME`: Set by the installer to the pnpm home directory.
- `PATH`: Updated by the installer to include pnpm binary locations.
- All user-provided environment variables.
- GitHub Actions runner environment variables.

**Note:** The environment is NOT manually patched to add `node_modules/.bin` to PATH because the installer already adds the correct pnpm location, and other mechanisms handle binary resolution.

### Output Visibility
Each install command is wrapped in GitHub Actions groups for collapsible logs:
```
::group::Running pnpm install ...
[command output]
::endgroup::
```
```

--------------------------------

### Example Cache Key

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/cache.md

A concrete example of a cache key generated by the pnpm action.

```text
pnpm-cache-Linux-x64-abc123def456...
```

--------------------------------

### Control pnpm Install Execution

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Determines whether and how to run 'pnpm install'. Accepts boolean, null, or detailed object configurations for custom install commands.

```yaml
with:
  run_install: true
```

--------------------------------

### Environment Variables Set by Installer

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/module-structure.md

Lists environment variables that are explicitly set by the installer, including PNPM_HOME and PATH modifications.

```text
Set by installer:
- PNPM_HOME — Home directory for pnpm self-updates
- PATH — Prepended with pnpm binary directories
```

--------------------------------

### pnpm installation with custom arguments in GitHub Actions

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-install.md

A GitHub Actions workflow snippet to run pnpm installation with custom command-line arguments.

```yaml
- uses: pnpm/action-setup@v6
  with:
    version: 9
    run_install: |
      args: [--strict-peer-dependencies, --frozen-lockfile]
```

--------------------------------

### Multiple pnpm installations with different options in GitHub Actions

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-install.md

A GitHub Actions workflow snippet demonstrating multiple pnpm installations with varied configurations like recursion, arguments, and working directories.

```yaml
- uses: pnpm/action-setup@v6
  with:
    version: 9
    run_install: |
      - recursive: true
        args: [--strict-peer-dependencies]
      - cwd: apps/web
        args: [--frozen-lockfile]
      - cwd: apps/api
        args: [--frozen-lockfile, --ignore-scripts]
```

--------------------------------

### Usage of pnpm action outputs

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Demonstrates how to access output variables like installation destination, binary path, and cache status in subsequent workflow steps.

```yaml
- uses: pnpm/action-setup@v6
  id: setup
  with:
    version: 9

- run: |
    echo "pnpm at: ${{ steps.setup.outputs.dest }}"
    echo "bin at: ${{ steps.setup.outputs.bin_dest }}"
    echo "cache hit: ${{ steps.setup.outputs.cache-hit }}"
```

--------------------------------

### RunInstall Type

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/inputs.md

Defines the structure for configuring a single `pnpm install` or `pnpm recursive install` command. This type specifies options like recursion, working directory, and additional arguments.

```APIDOC
## RunInstall Type

### Description
Configuration for a single `pnpm install` or `pnpm recursive install` command.

### Properties
| Property | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| `recursive` | `boolean` | No | `false` | Whether to run `pnpm recursive install` instead of `pnpm install`. |
| `cwd` | `string` | No | — | Working directory for the install command. If not specified, uses current process working directory. |
| `args` | `string[]` | No | — | Additional arguments to append after the install command, e.g., `['--ignore-scripts', '--strict-peer-dependencies']`. |
```

--------------------------------

### Recursive monorepo installation in GitHub Actions

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-install.md

A GitHub Actions workflow snippet for performing a recursive installation in a monorepo.

```yaml
- uses: pnpm/action-setup@v6
  with:
    version: 9
    run_install: |
      - recursive: true
```

--------------------------------

### Invalid YAML Input Example

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Demonstrates invalid YAML inputs for the 'run_install' configuration, highlighting incorrect types and unknown properties. Ensure YAML syntax is correct and properties match schema requirements.

```yaml
run_install: |
  recursive: 1  # must be boolean
```

```yaml
run_install: |
  args: --frozen-lockfile  # must be array
```

```yaml
run_install: |
  timeout: 300  # unknown property
```

--------------------------------

### Handle Installation Failure

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Catches non-zero exit codes from pnpm installation. Logs the error and allows for recovery steps.

```typescript
if (exitCode !== 0) {
  throw new Error(`Something went wrong, self-installer exits with code ${exitCode}`);
}
```

--------------------------------

### Handle pnpm Install Command Failure

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Logs errors when `pnpm install` or `pnpm recursive install` commands exit with a non-zero status code. This is non-fatal and allows the action to continue.

```typescript
throw new Error(`Command ${command} (cwd: ${cwd}) exits with status ${exitCode}`);
```

--------------------------------

### setOutputs()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/outputs.md

Sets GitHub Actions output variables for the installation destination and binary directory after a successful pnpm installation. These outputs can be referenced in subsequent workflow steps.

```APIDOC
## setOutputs()

### Description
Sets two action output variables, `dest` and `bin_dest`, which can be referenced in subsequent workflow steps using the `${{ steps.<step-id>.outputs.<output-name> }}` syntax. The `dest` output is the expanded path of the `dest` input, and `bin_dest` is the path to the pnpm binary directory.

### Method
TypeScript Function

### Signature
```typescript
function setOutputs(inputs: Inputs, binDest: string): void
```

### Parameters
#### Path Parameters
- **inputs** (`Inputs`) - Required - Configuration object containing the destination directory.
- **binDest** (`string`) - Required - Path to the pnpm binary directory (returned from `install()`).

### Returns
`void`

### Example
```typescript
import getInputs from '@pnpm/action-setup/inputs'
import install from '@pnpm/action-setup/install-pnpm'
import setOutputs from '@pnpm/action-setup/outputs'

const inputs = getInputs()
const binDest = await install(inputs)
if (binDest) {
  setOutputs(inputs, binDest)
}
```

### Output Variables Summary
- **dest** (`string`) - Expanded installation destination directory. Same as the `dest` input after tilde expansion.
- **bin_dest** (`string`) - Path to the directory containing `pnpm` and `pnpx` executables. Used for explicit path references; not required since PATH is already updated.
- **cache-hit** (`string` (boolean)) - Set by `cache-restore` module. `"true"` if pnpm store was restored from cache, `"false"` if cache miss.
```

--------------------------------

### Cache Key Format Example

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/cache.md

Illustrates the pattern for pnpm action cache keys, which includes runner OS, architecture, and lockfile hash.

```text
pnpm-cache-{RUNNER_OS}-{process.arch}-{lockfile_hash}
```

--------------------------------

### Parse Run Install Input

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/inputs.md

Parses the `run_install` GitHub Actions input string into a structured array of install configurations. Handles various input formats including null, boolean, object, and YAML arrays. Invalid YAML or schema violations will cause the process to exit.

```typescript
import { parseRunInstall } from '@pnpm/action-setup/inputs/run-install'

// Input: null, false, or empty
// Result: []

// Input: true
// Result: [{ recursive: true }]

// Input: { recursive: true, args: ['--strict-peer-dependencies'] }
// Result: [{ recursive: true, args: ['--strict-peer-dependencies'] }]

// Input: YAML array
// - recursive: true
//   args: [--ignore-scripts]
// - cwd: apps/web
// Result: [
//   { recursive: true, args: ['--ignore-scripts'] },
//   { cwd: 'apps/web' }
// ]
```

--------------------------------

### Valid run_install Inputs in YAML

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/types.md

Examples of how to configure the `run_install` input in a GitHub Actions workflow using YAML. The input is parsed and validated against a Zod schema.

```yaml
# Examples of valid run_install inputs:

run_install: false              # → []
run_install: true               # → [{ recursive: true }]
run_install: |
  recursive: true
  args: [--strict-peer-dependencies]
                                # → [{ recursive: true, args: [...] }]
run_install: |
  - recursive: true
  - cwd: apps/web
    args: [--frozen-lockfile]
                                # → [{ recursive: true }, { cwd: 'apps/web', args: [...] }]
```

--------------------------------

### Specify Installation Destination

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Defines the directory where pnpm files will be stored. Supports tilde expansion for the home directory.

```yaml
with:
  dest: "~/.pnpm-home"
```

--------------------------------

### Examples of pnpm Version Specification

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Demonstrates various ways to specify the pnpm version, including exact versions, ranges, and keywords like 'latest'.

```yaml
version: "9.0.0"        # Exact version
version: "9"            # Latest 9.x
version: "^9.0.0"       # Semver range
version: "latest"       # Latest release
version: "*"            # Latest version
```

--------------------------------

### Test Core pnpm Functionality

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Execute basic pnpm commands to ensure pnpm is functioning correctly after installation. This includes checking the version, store status, and listing installed packages.

```bash
- name: Test pnpm
  run: |
    pnpm --version
    pnpm store status
    pnpm list --depth=0
```

--------------------------------

### Run pnpm self-installation with runSelfInstaller()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/install-pnpm.md

The `runSelfInstaller()` function performs the complete pnpm installation workflow, including bootstrapping via npm and self-updating to the target version. It returns an object containing the exit code and the binary destination path.

```typescript
import { runSelfInstaller } from '@pnpm/action-setup/install-pnpm'
import getInputs from '@pnpm/action-setup/inputs'

const inputs = getInputs()
const result = await runSelfInstaller(inputs)
console.log(result.exitCode)  // 0 on success
console.log(result.binDest)   // e.g., "/home/runner/pnpm-home/bin"
```

--------------------------------

### Examples of pnpm Store Caching

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Shows how to enable or disable pnpm store caching. Caching is recommended for CI environments to reduce build times.

```yaml
cache: true
cache: false
```

--------------------------------

### Monorepo configuration with multiple lockfiles

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Configure caching and installation for monorepos with multiple lockfiles and workspaces. Caching is invalidated when any lockfile changes.

```yaml
with:
  version: 9
  cache: true
  cache_dependency_path: |
    pnpm-lock.yaml
    packages/*/pnpm-lock.yaml
  run_install: |
    - recursive: true
      args: [--strict-peer-dependencies]
    - cwd: packages/app
      args: [--frozen-lockfile]
    - cwd: packages/api
      args: [--frozen-lockfile]
```

--------------------------------

### runCommand()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/install-pnpm.md

Executes shell commands, such as `npm ci` or `pnpm self-update`, during the pnpm installation process. It allows specifying the command, arguments, working directory, and environment variables.

```APIDOC
## runCommand()

### Description
Internal function to execute shell commands during installation.

### Signature
```typescript
function runCommand(
  cmd: string,
  args: string[],
  opts: { cwd: string; env?: Record<string, string | undefined> }
): Promise<number>
```

### Parameters
#### Path Parameters
- **cmd** (string) - Required - Command to execute (e.g., `"npm"`, `"pnpm"`).
- **args** (string[]) - Required - Array of command-line arguments.
- **opts.cwd** (string) - Required - Working directory for the command.
- **opts.env** (Record<string, string | undefined>) - Optional - Environment variables. Merged with current `process.env`.

### Returns
`Promise<number>` — Exit code from the spawned process.

### Details
Spawns a child process with inherited stdio (output visible in logs). Used to run `npm ci` and `pnpm self-update` commands. On Windows, uses shell mode; on Unix, spawns directly.
```

--------------------------------

### Check pnpm Environment Variables and Path

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Verify that pnpm is correctly installed and accessible in your environment by checking the PNPM_HOME and PATH variables, and confirming the pnpm version. This helps ensure the action has set up the environment correctly.

```bash
- name: Debug environment
  run: |
    echo "PNPM_HOME=$PNPM_HOME"
    echo "PATH=$PATH"
    which pnpm
    pnpm --version
```

--------------------------------

### Configure Peer Dependency Conflict Resolution

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Provides a configuration to bypass strict peer dependency checks during installation. Use this when encountering `ERR_PNPM_PEER_DEP_CONFLICT`.

```yaml
run_install:
  args: [--no-strict-peer-dependencies]
```

--------------------------------

### Example Warning Messages for pruneStore Failure

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/pnpm-store.md

Illustrates the warning messages that are logged if the 'pnpm store prune' command fails or exits with a non-zero code. These are not fatal errors.

```bash
Warning: error from pnpm store prune
Warning: command pnpm store prune exits with code 1
```

--------------------------------

### Get pnpm Action Inputs

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/inputs.md

Retrieves and parses all GitHub Actions inputs into a typed configuration object. Paths are automatically expanded to resolve `~` to the home directory.

```typescript
import getInputs from '@pnpm/action-setup/inputs'

const inputs = getInputs()
console.log(inputs.version)      // e.g., "9.0.0"
console.log(inputs.cache)        // e.g., true
console.log(inputs.runInstall)   // e.g., [{ recursive: true, args: [...] }]
```

--------------------------------

### Handle pnpm Command Not Found Error

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Logs an error if the `pnpm` binary is not found in the PATH during command execution. This indicates a potential issue with the pnpm setup phase.

```typescript
throw new Error(`spawn ${error}`);
```

--------------------------------

### Documentation Structure

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/MANIFEST.md

Illustrates the directory structure of the generated documentation files for the pnpm/action-setup project.

```text
output/
├── README.md                          # Navigation guide
├── MANIFEST.md                        # This file
├── index.md                           # Overview & quick start
├── module-structure.md                # Architecture & modules
├── types.md                           # Type definitions
├── configuration.md                   # Input configuration
├── errors.md                          # Error reference
└── api-reference/
    ├── inputs.md                      # Input handling
    ├── install-pnpm.md                # pnpm installation
    ├── cache.md                       # Cache operations
    ├── outputs.md                     # Action outputs
    ├── pnpm-install.md                # Package installation
    └── pnpm-store.md                  # Store pruning
```

--------------------------------

### runSelfInstaller()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/install-pnpm.md

Performs the complete self-installation workflow by bootstrapping pnpm via npm and then self-updating to the target version. It returns an object containing the exit code and the binary destination path.

```APIDOC
## runSelfInstaller()

### Description
Performs the complete self-installation workflow: bootstraps pnpm via npm, then self-updates to the target version.

### Method
async

### Signature
runSelfInstaller(inputs: Inputs): Promise<SelfInstallerResult>

### Parameters
#### Path Parameters
- **inputs** (Inputs) - Required - Configuration object with version, dest, packageJsonFile, and standalone settings.

### Returns
`SelfInstallerResult` — Object with exit code and binary destination path.

### Description
This function implements the complete pnpm installation process:

1. **Detects Node.js version** — If system Node.js < v22.13 (or `standalone: true`), uses `@pnpm/exe` (bundled Node.js); otherwise uses regular pnpm.
2. **Bootstraps via npm** — Writes temporary package.json/package-lock.json and runs `npm ci` with bootstrap pnpm locked by committed lockfile.
3. **Self-updates** — Uses bootstrap pnpm to run `pnpm self-update <target-version>`, updating to the requested version.
4. **Sets up PATH** — Adds pnpm binary directories to PATH and sets PNPM_HOME environment variable.
5. **Handles Windows differences** — For standalone mode on Windows, uses native `@pnpm/exe` directory directly instead of npm shims.

The process reads target version from:
- `version` parameter (if provided)
- `packageManager` field in package.json (if exists)
- `devEngines.packageManager` field in package.json (takes priority over `packageManager`)

### Example
```typescript
import { runSelfInstaller } from '@pnpm/action-setup/install-pnpm'
import getInputs from '@pnpm/action-setup/inputs'

const inputs = getInputs()
const result = await runSelfInstaller(inputs)
console.log(result.exitCode)  // 0 on success
console.log(result.binDest)   // e.g., "/home/runner/pnpm-home/bin"
```
```

--------------------------------

### Install pnpm without packageManager field

Source: https://github.com/pnpm/action-setup/blob/master/README.md

Install pnpm when the repository does not have a package.json or it doesn't specify a packageManager. Requires the 'version' input.

```yaml
on:
  - push
  - pull_request

jobs:
  install:
    runs-on: ubuntu-latest

    steps:
      - uses: pnpm/action-setup@v6
        with:
          version: 10
```

--------------------------------

### parseRunInstall(inputName: string)

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/inputs.md

Parses the `run_install` GitHub Actions input string into a structured array of `RunInstall` objects. It handles various input formats including null, boolean, objects, and arrays, and validates the parsed YAML.

```APIDOC
## parseRunInstall(inputName: string)

### Description
Parses the `run_install` GitHub Actions input string into a structured array.

### Parameters
#### Path Parameters
- **inputName** (string) - Yes - Name of the input variable to parse (typically `"run_install"`).

### Returns
`RunInstall[]` — Array of install configurations parsed from YAML.

### Throws
- `Error` with exit code 1 if YAML parsing fails or schema validation fails

### Example
```typescript
import { parseRunInstall } from '@pnpm/action-setup/inputs/run-install'

// Input: null, false, or empty
// Result: []

// Input: true
// Result: [{ recursive: true }]

// Input: { recursive: true, args: ['--strict-peer-dependencies'] }
// Result: [{ recursive: true, args: ['--strict-peer-dependencies'] }]

// Input: YAML array
// - recursive: true
//   args: [--ignore-scripts]
// - cwd: apps/web
// Result: [
//   { recursive: true, args: ['--ignore-scripts'] },
//   { cwd: 'apps/web' }
// ]
```
```

--------------------------------

### Related Source Files Structure

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/MANIFEST.md

Illustrates the directory structure and main files within the 'src' folder of the pnpm/action-setup project. Helps in understanding the organization of the codebase and the purpose of key modules.

```text
src/
├── index.ts                           (Main entry point)
├── inputs/
│   ├── index.ts                       (Input parsing)
│   └── run-install.ts                 (Install config parsing)
├── install-pnpm/
│   ├── index.ts                       (Install wrapper)
│   ├── run.ts                         (Installation implementation)
│   └── bootstrap/                     (Pre-locked dependencies)
├── cache-restore/
│   ├── index.ts                       (Cache restoration)
│   └── run.ts                         (Cache implementation)
├── cache-save/
│   ├── index.ts                       (Cache persistence)
│   └── run.ts                         (Cache implementation)
├── outputs/
│   └── index.ts                       (Output setting)
├── pnpm-install/
│   └── index.ts                       (Install execution)
└── pnpm-store-prune/
    └── index.ts                       (Store pruning)
```

--------------------------------

### Restore pnpm Cache in GitHub Actions

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/cache.md

Restores the pnpm store directory from GitHub Actions cache. This function should be called after pnpm installation but before 'pnpm install'. It sets 'cache-hit' output and state variables for the post-action phase.

```typescript
import restoreCache from '@pnpm/action-setup/cache-restore'
import getInputs from '@pnpm/action-setup/inputs'

const inputs = getInputs()
await restoreCache(inputs)
// Cache is now restored (if available)
// Output 'cache-hit' is set for downstream steps
```

--------------------------------

### Bootstrap Mechanism for Standalone (@pnpm/exe)

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/module-structure.md

Details the bootstrapping process for the standalone @pnpm/exe using specific lockfiles and npm ci.

```text
For standalone (@pnpm/exe):
- src/install-pnpm/bootstrap/exe-lock.json — @pnpm/exe package locked version
- src/install-pnpm/bootstrap/package.json — Single dependency: `@pnpm/exe: <version>`
- Process: `npm ci` → bootstrap exe → `pnpm self-update <target>`
```

--------------------------------

### Bootstrap Mechanism for Regular pnpm

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/module-structure.md

Describes the process for bootstrapping regular pnpm using pre-verified lockfiles and npm ci.

```text
For regular pnpm:
- src/install-pnpm/bootstrap/pnpm-lock.json — pnpm package locked version
- src/install-pnpm/bootstrap/package.json — Single dependency: `pnpm: <version>`
- Process: `npm ci` → bootstrap pnpm → `pnpm self-update <target>`
```

--------------------------------

### Specify pnpm Version

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/configuration.md

Sets the exact version of pnpm to install. If not provided, the action attempts to read from the packageManager field in package.json.

```yaml
with:
  version: "9.0.0"
```

--------------------------------

### Enable Debug Logging for pnpm/action-setup

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Enable debug logging for the pnpm/action-setup action by setting the RUNNER_DEBUG and NODE_DEBUG environment variables. This is useful for diagnosing issues during action execution.

```yaml
- uses: pnpm/action-setup@v6
  with:
    version: 9
  env:
    RUNNER_DEBUG: "1"
    NODE_DEBUG: "module"
```

--------------------------------

### Inputs Interface Definition

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/types.md

Defines the configuration object for action inputs. Use this to configure pnpm version, destination, caching, and installation behavior.

```typescript
interface Inputs {
  readonly version?: string
  readonly dest: string
  readonly cache: boolean
  readonly cacheDependencyPath: string
  readonly runInstall: RunInstall[]
  readonly packageJsonFile: string
  readonly standalone: boolean
}
```

--------------------------------

### SelfInstallerResult Interface Definition

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/types.md

Defines the result object returned from the runSelfInstaller function. Includes the exit code of the installer and the destination path of the pnpm binary.

```typescript
interface SelfInstallerResult {
  readonly exitCode: number
  readonly binDest: string
}
```

--------------------------------

### Configuration Data Flow

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/module-structure.md

Illustrates how GitHub Actions inputs are parsed into an 'Inputs' object, which is then passed to various modules. This object contains configuration like version, destination, cache settings, and an array of runInstall configurations.

```plaintext
GitHub Actions Inputs (action.yml)
    ↓
getInputs()
    ↓
Inputs object
    ├── version, dest, cache, ...
    ├── runInstall: [RunInstall, RunInstall, ...]
    │   └── Each: { recursive?, cwd?, args? }
    └── Passed to all modules
```

--------------------------------

### Determine pnpm Version to Install

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/install-pnpm.md

Resolves the target pnpm version based on action inputs or package.json. Prioritizes explicit version inputs over package.json configurations.

```typescript
function readTargetVersion(opts: {
  readonly version?: string | undefined
  readonly packageJsonFile: string
}): string
```

--------------------------------

### Windows Environment Variable Considerations

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/module-structure.md

Highlights specific considerations for environment variable management on Windows, such as case-insensitivity and binary directory structures.

```text
Windows Considerations:
- PATH key lookup is case-insensitive
- Standalone mode uses different binary directory structure
- npm shims in `.bin` are avoided to prevent version shadowing
```

--------------------------------

### YAML: Using bin_dest for Custom pnpm Execution

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/outputs.md

Demonstrates how to explicitly use the `bin_dest` output variable to call the pnpm executable in a GitHub Actions workflow, ensuring the correct version is used.

```yaml
- name: Custom pnpm call
  run: |
    "${{ steps.pnpm.outputs.bin_dest }}/pnpm" install --frozen-lockfile
```

--------------------------------

### RunInstallInput Type Definition

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/types.md

Represents the raw input for the run_install action input before schema validation. It accepts null, boolean, a single RunInstall object, or an array of RunInstall objects.

```typescript
type RunInstallInput = null | boolean | RunInstall | RunInstall[]
```

--------------------------------

### Cache dependencies from multiple lockfiles

Source: https://github.com/pnpm/action-setup/blob/master/README.md

Configures caching using multiple lockfile paths, allowing for more granular cache management. Also specifies working directories for recursive installations.

```yaml
on:
  - push
  - pull_request

jobs:
  cache-and-install-multiple:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - uses: pnpm/action-setup@v6
        with:
          version: 10
          cache: true
          cache_dependency_path: |
            one/pnpm-lock.yaml
            two/pnpm-lock.yaml
          run_install: |
            - cwd: one
            - cwd: two
```

--------------------------------

### Conflicting pnpm Versions Example

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/errors.md

Illustrates a scenario where both the action input 'version' and the 'packageManager' in package.json specify different pnpm versions. This conflict triggers an error and requires resolution.

```yaml
# Action input: version 9.0.0
# package.json: packageManager = "pnpm@10.0.0"
# → Conflict! Error thrown
```

--------------------------------

### readTargetVersion()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/install-pnpm.md

Determines the specific version of pnpm to install based on explicit inputs or package.json configurations. It prioritizes explicit version inputs over package.json settings and handles potential version conflicts.

```APIDOC
## readTargetVersion()

### Description
Internal function to determine which pnpm version to install.

### Signature
```typescript
function readTargetVersion(opts: {
  readonly version?: string | undefined
  readonly packageJsonFile: string
}): string
```

### Parameters
#### Path Parameters
- **opts.version** (string | undefined) - Optional - Explicit version from action input. Takes precedence over package.json.
- **opts.packageJsonFile** (string) - Required - Path to package.json/package.yaml to read packageManager field.

### Returns
`string` — The resolved version string (e.g., "9.0.0", "10", "latest").

### Throws
- `Error` if `version` is specified AND `packageManager` in package.json specifies a different version
- `Error` if no version is found in inputs or package.json

### Details
Resolves the target pnpm version with this priority:
1. `version` parameter (from action input)
2. `devEngines.packageManager.version` field (if exists and name is "pnpm")
3. `packageManager` field (if starts with "pnpm@")
4. Throws error if none found

The function strips integrity hashes from `packageManager` values (e.g., `"pnpm@9.0.0+xyz"` → `"9.0.0"`).
```

--------------------------------

### Install pnpm using packageManager field

Source: https://github.com/pnpm/action-setup/blob/master/README.md

Omit the 'version' input to use the pnpm version specified in the packageManager field of package.json. This is useful when the project explicitly defines its pnpm version.

```yaml
on:
  - push
  - pull_request

jobs:
  install:
    runs-on: ubuntu-latest

    steps:
      - uses: pnpm/action-setup@v6
```

--------------------------------

### Cache Flow (Main Phase) Diagram

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/module-structure.md

Details the steps involved in restoring the cache during the main execution phase of the action.

```text
restoreCache(inputs)
    ├── getCacheDirectory() → pnpm store path
    ├── hashFiles(cacheDependencyPath) → cache key hash
    ├── restoreCache([cachePath], primaryKey)
    └── Save state: cache_path, cache_primary_key, cache_restored_key
```

--------------------------------

### getSystemNodeVersion()

Source: https://github.com/pnpm/action-setup/blob/master/_autodocs/api-reference/install-pnpm.md

Detects the major and minor version numbers of the system's Node.js installation by executing `node --version`. This is used to decide whether to use the standalone (bundled Node.js) mode for pnpm.

```APIDOC
## getSystemNodeVersion()

### Description
Internal function to detect the system Node.js version.

### Signature
```typescript
function getSystemNodeVersion(): Promise<{ major: number; minor: number }>
```

### Returns
`Promise<{ major: number; minor: number }>` — Object with major and minor version numbers. Returns `{ major: 0, minor: 0 }` if detection fails.

### Details
Spawns `node --version` process and parses the output to extract major and minor version numbers. Used to determine whether to use standalone (bundled Node.js) mode for pnpm.
```