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

Instead of running prs compile --watch in a terminal, you can let your AI tool trigger compilation automatically. Run prs hooks install once to wire prs compile into your tool's native hook system — no manual watch process needed. See the Hooks Guide for details.

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 inspect¶

Inspect how skill composition layers contribute to the final resolved skill. Shows per-property provenance (default) or per-layer breakdown.

prs inspect <skill-name> [options]

Arguments:

Options:

Examples:

# Show per-property provenance (default)
prs inspect code-review

# Show layer-level breakdown
prs inspect code-review --layers

# JSON output for tooling
prs inspect code-review --format json

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 serve¶

Start a local development server that connects the online playground to your local .prs files.

prs serve [options]

Options:

Examples:

# Start server with defaults (localhost:3000)
prs serve

# Custom port
prs serve --port 8080

# Expose on all interfaces (e.g. Docker, remote access)
prs serve --host 0.0.0.0

# Read-only mode (safe for shared environments)
prs serve --read-only

How it works:

1. Run prs serve in your project directory
2. The CLI prints a playground URL: https://getpromptscript.dev/playground/?server=127.0.0.1:3000
3. Open the URL - the playground loads your local .prs files
4. Edit in the playground or your editor - changes sync both ways via WebSocket
5. The playground reads your promptscript.yaml and applies your project configuration (enabled targets, formatting settings)

File discovery: The server scans only the source directory (.promptscript/ by default, or the directory from input.entry in your promptscript.yaml) and config files - not the entire repository.

API endpoints (used by the playground):

All compilation happens locally in your browser - no data is sent to any external server. The prs serve command only serves files to the playground running in your browser.

The server only accepts requests from https://getpromptscript.dev by default (CORS). Use --cors-origin to allow other origins. Use --read-only to prevent file modifications.

prs import¶

Import an existing AI instruction file to PromptScript format.

prs import <file> [options]

Options:

Examples:

# Import a CLAUDE.md file (format auto-detected)
prs import CLAUDE.md

# Import with explicit format
prs import .github/copilot-instructions.md --format github

# Preview without writing
prs import CLAUDE.md --dry-run

# Import and validate roundtrip fidelity
prs import CLAUDE.md --validate

# Import to custom output directory
prs import CLAUDE.md --output ./my-prompts

prs registry¶

Manage PromptScript registries. This command group contains subcommands for creating, validating, and publishing registries.

prs registry init¶

Create a new PromptScript registry.

prs registry init [directory] [options]

Options:

Examples:

# Interactive registry creation (default)
prs registry init

# Create with defaults (non-interactive)
prs registry init -y

# Create with custom name and namespaces
prs registry init --name my-registry --namespaces @core @stacks @fragments

# Create in a specific directory
prs registry init ./my-registry

# Skip seed configurations
prs registry init --no-seed

prs registry validate¶

Validate registry structure and manifest.

prs registry validate [path] [options]

Options:

Examples:

# Validate registry in current directory
prs registry validate

# Validate specific registry path
prs registry validate ./my-registry

# Strict mode (warnings become errors)
prs registry validate --strict

# JSON output for CI
prs registry validate --format json

prs registry publish¶

Publish registry to remote.

prs registry publish [path] [options]

Options:

Examples:

# Publish registry in current directory
prs registry publish

# Preview what would be published
prs registry publish --dry-run

# Publish with custom commit message
prs registry publish --message "feat: add new stack configs"

# Publish with a release tag
prs registry publish --tag v1.0.0

# Skip validation before publishing
prs registry publish --force

prs registry list¶

List all configured registry alias mappings, showing the merged result from project, user, and system sources.

prs registry list [options]

Options:

Examples:

# Show all resolved aliases
prs registry list

# Show only project-level aliases
prs registry list --source project

# JSON output
prs registry list --format json

Example output:

Registry aliases (merged: project > user > system)

  @company  github.com/acme/promptscript-base   [project]
  @team     github.com/acme/team-frontend        [project]
  @shared   github.com/acme/shared-libs          [user]

prs registry add¶

Add a registry alias to the project or user config.

prs registry add <alias> <url> [options]

Arguments:

Options:

Examples:

# Add alias to project config
prs registry add @company github.com/acme/promptscript-base

# Add alias to user config (available across all projects)
prs registry add @company github.com/acme/promptscript-base --global

prs lock¶

Generate or update the promptscript.lock lockfile. The lockfile records the exact resolved commit for every remote import, enabling reproducible builds.

prs lock [options]

Options:

Examples:

# Create or update lockfile
prs lock

# Preview changes without writing
prs lock --dry-run

The lockfile is also written automatically during prs compile when remote imports are present. Commit promptscript.lock to version control.

prs update¶

Update one or all remote dependencies to their latest allowed versions and refresh the lockfile.

prs update [package] [options]

Arguments:

Options:

Examples:

# Update all dependencies
prs update

# Update a specific package
prs update github.com/acme/promptscript-base

# Preview updates
prs update --dry-run

prs skills¶

Manage markdown-imported skills. See the Markdown Imports guide for full details.

prs skills add¶

Add a remote skill to the project. Inserts a @use directive into the entry .prs file and updates promptscript.lock.

prs skills add <source> [options]

Arguments:

Options:

Examples:

# Add a versioned skill
prs skills add github.com/anthropics/skills/commit@1.0.0

# Add a skill directory (auto-discovers SKILL.md)
prs skills add github.com/repo/skills/gitnexus

# Add to a specific .prs file
prs skills add github.com/anthropics/skills/commit@1.0.0 --file .promptscript/team.prs

# Preview what would change
prs skills add github.com/anthropics/skills/commit@1.0.0 --dry-run

prs skills remove¶

Remove a skill from the project. Removes the matching @use line and its lock entry.

prs skills remove <name> [options]

Arguments:

Options:

Examples:

# Remove by full path
prs skills remove github.com/anthropics/skills/commit@1.0.0

# Remove by partial match
prs skills remove commit

# Preview removal
prs skills remove commit --dry-run

prs skills list¶

List all skills imported in the current project via @use directives.

prs skills list

Examples:

# Show all imported skills
prs skills list

prs skills update¶

Update lock entries for markdown-sourced skills. Resets lock pins so the next prs compile re-resolves to the latest matching versions.

prs skills update [name] [options]

Arguments:

Options:

Examples:

# Update all markdown-sourced skills
prs skills update

# Update a specific skill
prs skills update github.com/anthropics/skills/commit

# Preview updates
prs skills update --dry-run

prs vendor¶

Manage the vendor directory for offline builds. Vendor mode copies all lockfile-resolved dependencies into .promptscript/vendor/.

prs vendor sync¶

Download all dependencies from the lockfile into the vendor directory.

prs vendor sync

After syncing, compilation uses the vendored files and makes no network requests.

prs vendor check¶

Verify that the vendor directory matches the current lockfile.

prs vendor check

Exits with code 1 if vendor is out of sync. Use in CI before compiling:

prs vendor check && prs compile

prs resolve¶

Debug the resolution chain for an import. Shows how an import path is resolved step-by-step: alias expansion, URL construction, cache lookup, and file path within the repository.

prs resolve <import> [options]

Arguments:

Options:

Examples:

# Resolve an aliased import
prs resolve @company/security

# Resolve a URL import
prs resolve github.com/acme/promptscript-base/@org/base

# JSON output for tooling
prs resolve @company/security --format json

Example output:

Resolving: @company/security

  1. Alias lookup:     @company -> github.com/acme/promptscript-base  [project config]
  2. URL construction: https://github.com/acme/promptscript-base.git
  3. Cache status:     HIT (commit: a3f8c2d, age: 12m)
  4. File path:        security.prs
  5. Resolved to:      ~/.promptscript/.cache/git/abc123/security.prs

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