CLI Reference¶

Complete reference for the PromptScript command-line interface.

Installation¶

npmpnpmyarn

npm install -g @promptscript/cli

pnpm add -g @promptscript/cli

yarn global add @promptscript/cli

Global Options¶

These options are available for all commands:

Option	Description
`-h, --help`	Display help information
`-V, --version`	Display version number
`--verbose`	Enable verbose output
`--quiet`	Suppress non-error output

Commands¶

prs init¶

Initialize PromptScript in the current directory.

prs init [options]

Options:

Option	Description
`-n, --name <name>`	Project name (auto-detected from package.json, etc.)
`-t, --team <team>`	Team namespace for organization
`--inherit <path>`	Inheritance path (e.g., `@company/team`)
`--registry <path>`	Registry path for shared configurations
`--targets <targets...>`	Target AI tools (github, claude, cursor)
`-i, --interactive`	Force interactive mode with prompts
`-y, --yes`	Skip prompts, use defaults

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

# 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)

Created Files:

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

prs compile¶

Compile PromptScript to target formats.

prs compile [options]

Options:

Option	Description
`-t, --target <target>`	Compile to specific target
`-f, --format <format>`	Output format (alias for `--target`)
`-a, --all`	Compile to all configured targets
`-w, --watch`	Watch mode for continuous compilation
`-o, --output <dir>`	Override output directory
`--dry-run`	Preview changes without writing
`-c, --config <path>`	Path to config file

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

Available Targets:

Target	Output File	Description
`github`	`.github/copilot-instructions.md`	GitHub Copilot
`claude`	`CLAUDE.md`	Claude Code
`cursor`	`.cursorrules`	Cursor

prs validate¶

Validate PromptScript files.

prs validate [options] [files...]

Options:

Option	Description
`--strict`	Treat warnings as errors
`--format <format>`	Output format (text, json)

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:

Code	Meaning
0	Validation passed
1	Validation errors found
2	Validation warnings found (with --strict)

prs diff¶

Show diff for compiled output.

prs diff [options]

Options:

Option	Description
`-t, --target <target>`	Show diff for specific target
`-a, --all`	Show diff for all targets
`--color`	Force colored output
`--no-color`	Disable colored output

Examples:

# Show all diffs
prs diff --all

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

prs pull¶

Pull updates from registry.

prs pull [options]

Options:

Option	Description
`-f, --force`	Force overwrite local changes
`--dry-run`	Preview changes without pulling

Examples:

# Pull registry updates
prs pull

# Force overwrite
prs pull --force

# Preview changes
prs pull --dry-run

prs check¶

Check configuration and dependencies.

prs check [options]

Options:

Option	Description
`--fix`	Attempt to fix issues

Examples:

# Check project health
prs check

# Check and fix
prs check --fix

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: .cursorrules

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

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

Environment Variables¶

Variable	Description
`PROMPTSCRIPT_CONFIG`	Path to config file
`PROMPTSCRIPT_REGISTRY`	Registry path or URL
`PROMPTSCRIPT_VERBOSE`	Enable verbose output
`NO_COLOR`	Disable colored output

Exit Codes¶

Code	Meaning
0	Success
1	Error occurred
2	Warning (with --strict)
130	Interrupted (Ctrl+C)

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 for debugging:

PROMPTSCRIPT_VERBOSE=1 prs compile