Docker
Run PromptScript CLI in Docker containers for consistent environments across development and CI/CD.
Quick Start
Pull the latest image and validate your PromptScript files:
# Pull the imagedocker pull ghcr.io/mrwogu/promptscript:latest
# Validate files in current directorydocker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest validate
# Compile to all targetsdocker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compileImage Tags
| Tag | Description | Example |
|---|---|---|
latest | Latest stable release | ghcr.io/mrwogu/promptscript:latest |
next | Latest pre-release (alpha/beta/rc) | ghcr.io/mrwogu/promptscript:next |
X.Y.Z | Specific version | ghcr.io/mrwogu/promptscript:1.0.0 |
X.Y | Latest patch of minor version | ghcr.io/mrwogu/promptscript:1.0 |
X | Latest minor of major version | ghcr.io/mrwogu/promptscript:1 |
All tags are generated automatically by CI/CD when a new version is released.
For production environments, pin to a specific version:
docker pull ghcr.io/mrwogu/promptscript:1.0.0Basic Usage
Initialize a New Project
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest \ init --name myproject --targets github claude opencode geminiValidate PromptScript Files
# Basic validationdocker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest validate
# Strict mode (treat warnings as errors)docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest validate --strict
# JSON output for parsingdocker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest validate --format jsonCompile to Target Formats
# Compile to all configured targetsdocker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile
# Dry run (preview without writing files)docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile --dry-run
# Watch mode for developmentdocker run --rm -it -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile --watchCheck Configuration
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest checkEnvironment Variables
Configure the CLI behavior through environment variables:
| Variable | Description | Example |
|---|---|---|
GITHUB_TOKEN | Authentication for private registries | ghp_xxxx |
PROMPTSCRIPT_VERBOSE | Enable verbose output | 1 |
NO_COLOR | Disable colored output | 1 |
Using Environment Variables
# With private registry authenticationdocker run --rm \ -v $(pwd):/workspace \ -e GITHUB_TOKEN="$GITHUB_TOKEN" \ ghcr.io/mrwogu/promptscript:latest pull
# Verbose outputdocker run --rm \ -v $(pwd):/workspace \ -e PROMPTSCRIPT_VERBOSE=1 \ ghcr.io/mrwogu/promptscript:latest compile
# Disable colors (useful for CI logs)docker run --rm \ -v $(pwd):/workspace \ -e NO_COLOR=1 \ ghcr.io/mrwogu/promptscript:latest validateCI/CD Integration
GitHub Actions
name: PromptScript
on: push: paths: - '.promptscript/**' - 'promptscript.yaml'
jobs: validate: runs-on: ubuntu-latest container: image: ghcr.io/mrwogu/promptscript:latest steps: - uses: actions/checkout@v4
- name: Validate run: node /app/bin/prs.js validate --strict
- name: Compile run: node /app/bin/prs.js compile
- name: Check drift run: | git config --global --add safe.directory "$GITHUB_WORKSPACE" if ! git diff --quiet; then echo "::error::Compiled files are out of sync" exit 1 fiGitLab CI
promptscript: image: ghcr.io/mrwogu/promptscript:latest script: - node /app/bin/prs.js validate --strict - node /app/bin/prs.js compile - git diff --exit-code rules: - changes: - .promptscript/**/* - promptscript.yamlJenkins
pipeline { agent { docker { image 'ghcr.io/mrwogu/promptscript:latest' } } stages { stage('Validate') { steps { sh 'node /app/bin/prs.js validate --strict' } } stage('Compile') { steps { sh 'node /app/bin/prs.js compile' } } stage('Check Drift') { steps { sh 'git diff --exit-code' } } }}Azure DevOps
pool: vmImage: 'ubuntu-latest'
container: ghcr.io/mrwogu/promptscript:latest
steps: - checkout: self
- script: node /app/bin/prs.js validate --strict displayName: 'Validate PromptScript'
- script: node /app/bin/prs.js compile displayName: 'Compile PromptScript'
- script: git diff --exit-code displayName: 'Check drift'Private Registries
When using a private PromptScript registry, pass your authentication token:
# Pull from private registrydocker run --rm \ -v $(pwd):/workspace \ -e GITHUB_TOKEN="$GITHUB_TOKEN" \ ghcr.io/mrwogu/promptscript:latest pull
# Compile with registry accessdocker run --rm \ -v $(pwd):/workspace \ -e GITHUB_TOKEN="$GITHUB_TOKEN" \ ghcr.io/mrwogu/promptscript:latest compileFor CI/CD, use secrets:
# GitHub Actions- name: Compile with registry run: | docker run --rm \ -v ${{ github.workspace }}:/workspace \ -e GITHUB_TOKEN=${{ secrets.REGISTRY_TOKEN }} \ ghcr.io/mrwogu/promptscript:latest compilePlayground Server
Run the PromptScript playground connected to your local files using Docker:
# Using docker composedocker compose up playground
# Or directlydocker run --rm -p 3000:3000 -v $(pwd):/workspace \ ghcr.io/mrwogu/promptscript:latest \ serve --host 0.0.0.0Then open: https://getpromptscript.dev/playground/?server=localhost:3000
The playground will load your local .prs files and sync changes in real time. See prs serve for all options.
For read-only access (e.g. demos or shared environments):
docker run --rm -p 3000:3000 -v $(pwd):/workspace:ro \ ghcr.io/mrwogu/promptscript:latest \ serve --host 0.0.0.0 --read-onlyBuilding Locally
Build the Docker image from source:
# Clone the repositorygit clone https://github.com/mrwogu/promptscript.gitcd promptscript
# Build the imagedocker build -t promptscript:local .
# Test your builddocker run --rm promptscript:local --versiondocker run --rm -v $(pwd):/workspace promptscript:local validateTroubleshooting
Permission Denied
If you see permission errors when writing files:
Error: EACCES: permission deniedThe container runs as non-root user (UID 1000). Ensure your mounted directory is writable:
# Check current user IDid -u
# If not 1000, you may need to adjust permissions or run as rootdocker run --rm -u root -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compileGit Safe Directory
If you see git errors about unsafe directories:
fatal: detected dubious ownership in repositoryThe image configures /workspace as a safe directory. Ensure you’re mounting to /workspace:
# Correct - mount to /workspacedocker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile
# Incorrect - different mount pointdocker run --rm -v $(pwd):/app ghcr.io/mrwogu/promptscript:latest compileInteractive Commands
For commands that require input (like init without flags), use -it:
docker run --rm -it -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest initContainer Not Found
If the image pull fails:
# Verify you can access GitHub Container Registrydocker login ghcr.io
# Try pulling with explicit registrydocker pull ghcr.io/mrwogu/promptscript:latestDebug Mode
Enable verbose output for troubleshooting:
docker run --rm \ -v $(pwd):/workspace \ -e PROMPTSCRIPT_VERBOSE=1 \ ghcr.io/mrwogu/promptscript:latest compileShell Access
For debugging, access the container shell:
docker run --rm -it --entrypoint sh ghcr.io/mrwogu/promptscript:latestImage Details
| Property | Value |
|---|---|
| Base image | node:25-alpine |
| Working directory | /workspace |
| User | node (UID 1000) |
| Entrypoint | node /app/bin/prs.js |
| Platforms | linux/amd64, linux/arm64 |
The image includes:
- Node.js 25 runtime
- Git (required for
prs pull) - PromptScript CLI with production dependencies
See Also
- CI/CD Integration - npm-based CI/CD configuration
- CLI Reference - Full CLI command reference
- Configuration -
promptscript.yamloptions