CLI Reference¶

Complete reference for the PromptScript command-line interface.

Installation¶

npm install -g @promptscript/cli

pnpm add -g @promptscript/cli

yarn global add @promptscript/cli

Global Options¶

These options are available for all commands:

Commands¶

prs init¶

Initialize PromptScript in the current directory.

prs init [options]

Options:

Examples:

# Interactive initialization (default)
prs init

# Quick initialization with defaults
prs init -y

# Initialize with custom project name
prs init --name my-project

# Initialize for a specific team with inheritance
prs init --team frontend --inherit @frontend/team

# Initialize with specific targets only
prs init --targets github claude

# Initialize with migration skill for existing projects
prs init --migrate

# Full non-interactive setup
prs init -n my-project --inherit @company/team --targets github claude cursor

Auto-detection:

The init command automatically detects:

• Project name from package.json, pyproject.toml, Cargo.toml, or go.mod
• Languages (TypeScript, Python, Rust, Go, etc.)
• Frameworks (React, Next.js, Django, FastAPI, etc.)
• Existing AI tools (GitHub Copilot, Claude, Cursor configurations)
• Prettier configuration (.prettierrc, .prettierrc.json, .prettierrc.yaml, .prettierrc.yml)

Prettier Integration:

If a Prettier configuration file is detected:

• Displays: Prettier config detected: .prettierrc
• Adds formatting: { prettier: true } to enable auto-detection during compilation
• Output formatting will respect your project's Prettier settings (tabWidth, proseWrap, printWidth)

If no Prettier configuration is found:

• Displays: No Prettier config found
• Adds default formatting options: formatting: { tabWidth: 2, proseWrap: preserve }

Created Files:

• promptscript.yaml - Configuration file (includes formatting settings)
• .promptscript/project.prs - Main instructions file

prs compile¶

Compile PromptScript to target formats.

prs compile [options]

Options:

Examples:

# Compile all targets (default)
prs compile

# Compile specific target
prs compile --target github
prs compile --target claude
prs compile --target cursor

# Using --format (alias for --target)
prs compile --format github
prs compile -f claude

# Watch mode
prs compile --watch

# Preview changes
prs compile --dry-run

# Custom config
prs compile --config ./custom.config.yaml

# Verbose output (shows pipeline stages, files, timing)
prs compile --verbose

# Debug output (includes AST details, cache info, validation rules)
prs compile --debug

Available Targets:

prs validate¶

Validate PromptScript files.

prs validate [options] [files...]

Options:

Examples:

# Validate current project
prs validate

# Validate with strict mode
prs validate --strict

# Validate specific files
prs validate .promptscript/project.prs

# JSON output for CI
prs validate --format json

Exit Codes:

prs diff¶

Show diff for compiled output.

prs diff [options]

Options:

Examples:

# Show all diffs
prs diff --all

# Show diff for specific target
prs diff --target github

prs pull¶

Pull updates from registry. Supports local, HTTP, and Git registries.

prs pull [options]

Options:

Examples:

# Pull registry updates
prs pull

# Force overwrite
prs pull --force

# Preview changes
prs pull --dry-run

# Pull from specific Git branch
prs pull --branch develop

# Pull from specific Git tag
prs pull --tag v1.0.0

# Pull from specific commit
prs pull --commit abc123

# Force fresh clone (ignore cache)
prs pull --refresh

The --branch, --tag, --commit, and --refresh options only apply to Git registries. For local or HTTP registries, these options are ignored.

prs check¶

Check configuration and dependencies.

prs check [options]

Examples:

# Check project health
prs check

prs update-check¶

Check for CLI updates.

prs update-check

Examples:

# Check if a newer version is available
prs update-check

Configuration File¶

The CLI uses promptscript.yaml by default. Override with --config:

# Input settings
input:
  entry: .promptscript/project.prs

# Registry configuration
registry:
  path: ./registry
  # Or remote URL
  # url: https://github.com/org/registry

# Output targets
targets:
  github:
    enabled: true
    output: .github/copilot-instructions.md

  claude:
    enabled: true
    output: CLAUDE.md

  cursor:
    enabled: true
    output: .cursor/rules/project.mdc

  antigravity:
    enabled: true
    output: .agent/rules/project.md

# Validation settings
validation:
  strict: false
  ignoreWarnings: []

# Watch settings
watch:
  include:
    - '.promptscript/**/*.prs'
  exclude:
    - '**/node_modules/**'

Environment Variables¶

Exit Codes¶

Troubleshooting¶

Common Issues¶

Config file not found:

Error: Configuration file not found

Run prs init to create a configuration file.

Registry not accessible:

Error: Cannot access registry at ./registry

Ensure the registry path exists or configure a valid remote URL.

Invalid PromptScript syntax:

Error: Parse error at line 10

Check your .prs file syntax. Use prs validate for detailed errors.

Debug Mode¶

Enable verbose output to see compilation progress:

prs compile --verbose
# or
PROMPTSCRIPT_VERBOSE=1 prs compile

For maximum detail (AST info, cache hits, validation rules), use debug mode:

prs compile --debug
# or
PROMPTSCRIPT_DEBUG=1 prs compile

Verbose output shows:

• Pipeline stages (Resolve, Validate, Format)
• Files being parsed and resolved
• Import and inheritance resolution paths
• Per-stage timing

Debug output additionally shows:

• AST node counts
• Cache hits and stores
• Individual validation rules being executed
• Formatter conventions used