@promptscript/cli

Part of the PromptScript ecosystem - The Prompt-as-Code for AI Instructions.

Command-line interface for PromptScript. Compile, validate, and manage AI instructions at enterprise scale.

🏗️ Architecture

The CLI bundles all internal packages into a single distributable:

@promptscript/cli (published)
│
├─► compiler (pipeline orchestration)
│   ├─► resolver
│   ├─► validator ─────► core
│   └─► formatters ────► core
│
└─► resolver (inheritance & import resolution)
    ├─► parser ────────► core
    └───────────────────► core

See the PromptScript monorepo for development details.

Installation

npm install -g @promptscript/cli
# or
pnpm add -g @promptscript/cli

Commands

Initialize Project

prs init [options]

Options:
  -n, --name <name>        Project name (auto-detected)
  -t, --team <team>        Team namespace
  --inherit <path>         Inheritance path (e.g., @company/team)
  --registry <path>        Registry path
  --targets <targets...>   Target AI tools (github, claude, cursor)
  -i, --interactive        Force interactive mode
  -y, --yes                Skip prompts, use defaults
  -f, --force              Force reinitialize even if already initialized

Auto-detection: Project name, languages, frameworks, and existing AI tool configurations.

Creates:

• promptscript.yaml - Configuration file
• .promptscript/project.prs - Main project file

Compile

prs compile [options]

Options:
  -t, --target <target>   Specific target (github, claude, cursor)
  -a, --all               All configured targets (default)
  -w, --watch             Watch mode for continuous compilation (uses chokidar)
  -o, --output <dir>      Output directory
  --dry-run               Preview changes without writing files
  --force                 Force overwrite existing files without prompts
  --registry <path>       Path or URL to registry
  --verbose               Show detailed compilation progress
  --debug                 Show debug information (includes verbose)

Watch Mode: Uses chokidar for reliable file watching across all platforms. Automatically recompiles when .prs files change.

Overwrite Protection: By default, prs compile protects user-created files from accidental overwriting. Files generated by PromptScript contain a marker (> Auto-generated by PromptScript) and are overwritten silently. For files without this marker:

• Interactive mode: You'll be prompted to overwrite (y/N/a)
• Non-interactive mode: Compilation fails with a list of conflicting files

Use --force to skip all prompts and overwrite everything. Use --dry-run to preview conflicts before writing.

Validate

prs validate [options]

Options:
  --strict                Treat warnings as errors
  --format <format>       Output format (text, json)

Pull Updates

prs pull [options]

Options:
  -f, --force             Force overwrite local files

Show Diff

prs diff [options]

Options:
  -t, --target <target>   Specific target to diff
  --full                  Show full diff without truncation
  --no-pager              Disable pager output

By default, diff output is shown through a pager (less) for easy scrolling. Use --no-pager to disable this behavior. You can customize the pager via the PAGER environment variable.

Check for Updates

prs update-check

Checks if a newer version of the CLI is available on npm and displays the result:

@promptscript/cli v1.0.0
✓ Up to date

Or if an update is available:

@promptscript/cli v1.0.0
Update available: 1.0.0 → 1.1.0 (npm i -g @promptscript/cli)

Automatic Update Checks: The CLI automatically checks for updates once every 24 hours when running any command. The check is non-blocking and cached locally. To disable automatic checks, set the PROMPTSCRIPT_NO_UPDATE_CHECK environment variable:

PROMPTSCRIPT_NO_UPDATE_CHECK=1 prs compile

Environment Variables

Configuration

Create a promptscript.yaml file:

version: '1'

project:
  id: my-project
  team: frontend

inherit: '@frontend/team'

registry:
  path: './registry'
  cache: true # Enable HTTP registry caching
  auth: # Authentication for HTTP registry
    type: bearer
    token: ${REGISTRY_TOKEN} # Environment variable interpolation

input:
  entry: '.promptscript/project.prs'
  include:
    - '.promptscript/**/*.prs'
  exclude:
    - '**/*.local.prs'

output:
  dir: '.' # Output base directory
  clean: false # Clean output before compile
  targets:
    github: '.github/copilot-instructions.md'
    claude: 'CLAUDE.md'
    cursor: '.cursor/rules/project.mdc'

watch:
  debounce: 300 # Debounce time in ms
  ignored:
    - '**/node_modules/**'

targets:
  - github
  - claude
  - cursor

validation:
  requiredGuards:
    - '@core/guards/compliance'
  rules:
    empty-block: warn

Output Examples

Success

✔ Compilation successful

  ✓ .github/copilot-instructions.md
  ✓ CLAUDE.md
  ✓ .cursor/rules/project.mdc

Stats: 234ms (resolve: 45ms, validate: 8ms, format: 181ms)

Watch Mode

👀 Watching for changes...

[12:34:56] File changed: .promptscript/project.prs
✔ Compilation successful (156ms)

  ✓ .github/copilot-instructions.md
  ✓ CLAUDE.md

Error

✖ Compilation failed

  ✗ @meta.id is required
    at .promptscript/project.prs:1:1
    suggestion: Add id: "your-id" to @meta

License

MIT