Skip to content
PAM

Extend the PAM CLI

Applications and Composer packages can expose embedded PHP scripts or native executables. PAM validates names, canonicalizes targets, rejects paths outside their owner and prevents built-in or duplicate command shadowing.

Application commands

Section titled “Application commands”

Add commands to pam.json:

{
  "$schema": "https://push-in.github.io/pam-docs/schemas/pam.schema.json",
  "schema": 1,
  "type": 1,
  "name": "billing-api",
  "commands": {
    "billing:reconcile": {
      "script": "bin/reconcile.php",
      "description": "Reconcile pending invoices"
    }
  }
}
Terminal window
pam commands
pam billing:reconcile --since=yesterday

Use a string when no custom description is needed:

{"commands":{"app:warm":"bin/warm.php"}}

Package commands

Section titled “Package commands”

A Composer package registers commands under extra.pam.commands. Paths are relative to the installed package root. PAM reads Composer’s canonical install-path metadata and honors a custom config.vendor-dir:

{
  "name": "vendor/pam-inspector",
  "extra": {
    "pam": {
      "commands": {
        "inspector:snapshot": {
          "script": "bin/snapshot.php",
          "description": "Capture an application snapshot"
        }
      }
    }
  }
}

Use bin when the package ships a native CLI:

{
  "extra": {
    "pam": {
      "commands": {
        "inspector:watch": {
          "bin": "bin/pam-inspector",
          "arguments": ["watch"],
          "description": "Watch application diagnostics"
        }
      }
    }
  }
}

arguments is an optional bounded prefix added before user arguments. script runs in PAM’s embedded PHP runtime. bin receives the project as its working directory, all command arguments, and the absolute PAM executable in PAM_BINARY. A definition must contain exactly one of script or bin.

Installed product packages may own contextual commands such as dev, build, package, desktop, and mobile. Their command takes precedence over the runtime’s migration adapter. Runtime-authority commands such as start, process supervision, composer, exec, and self-update cannot be shadowed.

Command names contain lowercase ASCII letters, integers, :, -, or _, start with a letter/integer and contain at most 96 bytes. A package cannot shadow PAM or another registered command; pam doctor and discovery fail on a duplicate.

Machine-readable discovery

Section titled “Machine-readable discovery”
Terminal window
pam commands --json
pam commands --names

Use this output for launchers and editor integrations. Do not parse decorated terminal output. --names is the newline-delimited surface used by generated Bash, Zsh, Fish and PowerShell completion. The project manifest follows the public pam.schema.json JSON Schema.