CLI Reference

Complete command-line reference for all prompd CLI implementations. Commands are consistent across Python, Go, and Node.js.

Global Options

Option	Description
--version	Show version number
--help	Show help message
--verbose, -v	Enable verbose logging
--quiet, -q	Suppress all output except errors

Commands

prompd init

Initialize a folder with example.prmd and manifest.json.

prompd init <path>

Examples:

prompd init .
prompd init ./my-project

prompd compile

Compile a .prmd file with parameters and return the compiled prompt text.

prompd compile <file> [options]

Option	Description
--to-markdown	Compile to markdown format
--to-openai-json	Compile to OpenAI JSON format
--to-anthropic-json	Compile to Anthropic JSON format
--output, -o	Output file path
--param, -p	Set parameter values (repeatable)
--param-file	Load parameters from JSON file

Examples:

# Compile with parameters
prompd compile prompt.prmd -p name=Alice -p style=formal

# Load parameters from file
prompd compile prompt.prmd --param-file params.json

# Save compiled output
prompd compile prompt.prmd -p name=Bob -o rendered.txt

# Combine command line and file parameters
prompd compile prompt.prmd --param-file params.json -p override=value

prompd run

Run a .prmd file with an LLM provider.

prompd run <file> --provider <provider> --model <model> [options]

Option	Description
--provider	LLM provider (openai, anthropic, ollama)
--model	Model name (gpt-4, claude-3-opus, etc.)
-p, --param	Set parameter value (key=value, repeatable)
-f, --param-file	Load parameters from JSON file
--api-key	Override API key for provider
-o, --output	Save response to file
--version	Execute a specific version
--stream	Enable streaming output

Examples:

# Basic execution
prompd run prompt.prmd --provider openai --model gpt-4

# With parameters
prompd run prompt.prmd --provider openai --model gpt-4 \
  -p language=Python \
  -p style=detailed

# With parameter file
prompd run prompt.prmd --provider anthropic --model claude-3-opus \
  -f params.json

# Execute a specific version
prompd run prompt.prmd --provider openai --model gpt-4 \
  --version 1.2.3 -p name=Alice

# Pass array parameters (JSON syntax)
prompd run prompt.prmd --provider openai --model gpt-4 \
  -p tags='["api","backend","nodejs"]'

# Pass object parameters (JSON syntax)
prompd run prompt.prmd --provider openai --model gpt-4 \
  -p user='{"name":"Alice","role":"admin"}'

Parameter type syntax

Use single quotes ' around JSON values and double quotes " inside the JSON:

-p name="John Doe"                      # string
-p count=42                             # number / integer
-p price=9.99                           # float
-p enabled=true                         # boolean
-p tags='["api","backend"]'             # array (JSON)
-p config='{"timeout":30}'             # object (JSON)
-p criteria='[{"name":"clarity","weight":0.5}]'  # json (array of objects)
-p source_file="./prompt.txt"           # file (caller supplies content as string)
-p image_data="iVBORw0KGgo..."          # base64 (binary encoded as string)

prompd validate

Validate a .prmd file’s syntax and structure.

prompd validate <file> [options]

Option	Description
-v, --verbose	Show detailed validation results
--git	Include git history consistency checks
--version-only	Only validate version-related aspects
--check-overrides	Validate section overrides against parent

Validation checks include:

• YAML syntax validity
• Required fields presence
• Name format (kebab-case)
• Version format (semantic)
• Parameter definitions
• Variable references
• Type consistency
• Section override validation (with --check-overrides)

prompd show

Display the structure and parameters of a .prmd file.

prompd show <file> [options]

Option	Description
--sections	Show available section IDs for override
--verbose	Show detailed section information

# Show sections available for override
prompd show template.prmd --sections

prompd pack

Shortcut for prompd package create. Creates a .pdpkg package from a directory.

prompd pack <source-directory> [output-file]

Option	Description
-n, --name	Package name (overrides manifest.json)
-V, --version	Package version (overrides manifest.json)
-d, --description	Package description
-a, --author	Package author

Examples:

prompd pack . my-package.pdpkg
prompd pack ./my-project
prompd pack . my-package.pdpkg \
  --name "@myorg/toolkit" \
  --version "1.0.0"

prompd package

Manage package creation and validation.

prompd package <command> [options]

Subcommands:

• create - Create a new package
• validate - Validate package structure
• info - Show package information

prompd login

Authenticate with the prompd registry.

prompd login

Opens browser for authentication flow with the registry.

prompd publish

Publish a package to the registry.

prompd publish <package-file>

prompd install

Install a package from the registry.

prompd install <package-name>[@version]

# Install all dependencies from manifest.json
prompd install

# Install specific version
prompd install @prompd.io/package-name@1.0.0

# Install as dev dependency
prompd install @prompd.io/package-name --dev

# Install globally
prompd install @prompd.io/package-name --global

Version format

Do NOT include the v prefix in version numbers. Use @prompd.io/package@1.0.0, not @prompd.io/package@v1.0.0.

prompd search

Search for packages in the registry.

prompd search <query>

prompd list

List installed packages or available .prmd files.

prompd list [options]

Option	Description
--global	List global packages
--json	Output in JSON format
-p, --path	Directory to search
-d, --detailed	Show detailed information

prompd uninstall

Uninstall a package.

prompd uninstall <package-name>

prompd git

Git operations for .prmd files.

prompd git add <files...>          # Add to staging
prompd git remove <files...>       # Remove from tracking
prompd git status                  # Show status
prompd git commit -m <message>     # Commit staged files
prompd git checkout <file> <ver>   # Checkout specific version

prompd version

Manage semantic versions with git integration.

prompd version bump <file> <type>    # Bump version (major/minor/patch)
prompd version history <file>        # Show version history
prompd version diff <file> <v1> [v2] # Compare versions
prompd version validate <file>       # Validate version consistency
prompd version suggest <file>        # Get bump suggestions

prompd config

Configuration management.

prompd config show                        # Show all settings
prompd config provider list               # List providers
prompd config provider add <name> <url> <models...>  # Add provider
prompd config provider show <name>        # Show provider details
prompd config provider remove <name>      # Remove provider
prompd config provider setkey <name> <key> # Set API key
prompd config registry list               # List registries
prompd config registry add <name> <url>   # Add registry
prompd config registry remove <name>      # Remove registry
prompd config registry set-default <name> # Set default registry

Configuration

Environment Variables

# API Keys
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export OLLAMA_HOST="http://localhost:11434"

# Defaults
export PROMPD_DEFAULT_PROVIDER="openai"
export PROMPD_DEFAULT_MODEL="gpt-4"

Configuration File

Create ~/.prompd/config.yaml:

default_provider: openai
default_model: gpt-4
timeout: 30
max_retries: 3
verbose: false
api_keys:
  openai: sk-...
  anthropic: sk-ant-...
registry:
  default: prompdhub
  registries:
    prompdhub:
      url: https://registry.prompdhub.ai

Parameter Precedence

Parameters are resolved in this order (highest to lowest priority):

1. Command-line parameters (-p key=value)
2. Parameter files (-f file.json)
3. Default values in .prmd file
4. Environment variables

Exit Codes

Code	Meaning
0	Success
1	General error
2	Validation error
3	Provider error
4	Configuration error
5	File not found

Complete Workflow Example

# 1. Initialize
prompd init .

# 2. Validate
prompd validate example.prmd

# 3. Compile
prompd compile example.prmd --to-markdown

# 4. Run with provider
prompd run example.prmd \
  --provider openai --model gpt-4o \
  --param text="Great product!"

# 5. Package
prompd package create . sentiment-analyzer.pdpkg

# 6. Publish
prompd login
prompd publish sentiment-analyzer.pdpkg

Troubleshooting

Common Issues

“Missing required field ‘name’” - The .prmd file must have a name field in the YAML frontmatter.

“Undefined variable ‘X’ referenced” - All variables used in content must be defined in the parameters section.

“Provider error: No API key” - Set the API key via environment variable or config file.

“Invalid semantic version” - Version must follow format: major.minor.patch (e.g., 1.2.3)

Debug Mode

prompd run prompt.prmd --provider openai --model gpt-4 -v