Skip to content

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:

Terminal window
# Pull the image
docker pull ghcr.io/mrwogu/promptscript:latest
# Validate files in current directory
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest validate
# Compile to all targets
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile

Image Tags

TagDescriptionExample
latestLatest stable releaseghcr.io/mrwogu/promptscript:latest
nextLatest pre-release (alpha/beta/rc)ghcr.io/mrwogu/promptscript:next
X.Y.ZSpecific versionghcr.io/mrwogu/promptscript:1.0.0
X.YLatest patch of minor versionghcr.io/mrwogu/promptscript:1.0
XLatest minor of major versionghcr.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:

Terminal window
docker pull ghcr.io/mrwogu/promptscript:1.0.0

Basic Usage

Initialize a New Project

Terminal window
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest \
init --name myproject --targets github claude opencode gemini

Validate PromptScript Files

Terminal window
# Basic validation
docker 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 parsing
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest validate --format json

Compile to Target Formats

Terminal window
# Compile to all configured targets
docker 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 development
docker run --rm -it -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile --watch

Check Configuration

Terminal window
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest check

Environment Variables

Configure the CLI behavior through environment variables:

VariableDescriptionExample
GITHUB_TOKENAuthentication for private registriesghp_xxxx
PROMPTSCRIPT_VERBOSEEnable verbose output1
NO_COLORDisable colored output1

Using Environment Variables

Terminal window
# With private registry authentication
docker run --rm \
-v $(pwd):/workspace \
-e GITHUB_TOKEN="$GITHUB_TOKEN" \
ghcr.io/mrwogu/promptscript:latest pull
# Verbose output
docker 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 validate

CI/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
fi

GitLab 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.yaml

Jenkins

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:

Terminal window
# Pull from private registry
docker run --rm \
-v $(pwd):/workspace \
-e GITHUB_TOKEN="$GITHUB_TOKEN" \
ghcr.io/mrwogu/promptscript:latest pull
# Compile with registry access
docker run --rm \
-v $(pwd):/workspace \
-e GITHUB_TOKEN="$GITHUB_TOKEN" \
ghcr.io/mrwogu/promptscript:latest compile

For 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 compile

Playground Server

Run the PromptScript playground connected to your local files using Docker:

Terminal window
# Using docker compose
docker compose up playground
# Or directly
docker run --rm -p 3000:3000 -v $(pwd):/workspace \
ghcr.io/mrwogu/promptscript:latest \
serve --host 0.0.0.0

Then 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):

Terminal window
docker run --rm -p 3000:3000 -v $(pwd):/workspace:ro \
ghcr.io/mrwogu/promptscript:latest \
serve --host 0.0.0.0 --read-only

Building Locally

Build the Docker image from source:

Terminal window
# Clone the repository
git clone https://github.com/mrwogu/promptscript.git
cd promptscript
# Build the image
docker build -t promptscript:local .
# Test your build
docker run --rm promptscript:local --version
docker run --rm -v $(pwd):/workspace promptscript:local validate

Troubleshooting

Permission Denied

If you see permission errors when writing files:

Error: EACCES: permission denied

The container runs as non-root user (UID 1000). Ensure your mounted directory is writable:

Terminal window
# Check current user ID
id -u
# If not 1000, you may need to adjust permissions or run as root
docker run --rm -u root -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile

Git Safe Directory

If you see git errors about unsafe directories:

fatal: detected dubious ownership in repository

The image configures /workspace as a safe directory. Ensure you’re mounting to /workspace:

Terminal window
# Correct - mount to /workspace
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile
# Incorrect - different mount point
docker run --rm -v $(pwd):/app ghcr.io/mrwogu/promptscript:latest compile

Interactive Commands

For commands that require input (like init without flags), use -it:

Terminal window
docker run --rm -it -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest init

Container Not Found

If the image pull fails:

Terminal window
# Verify you can access GitHub Container Registry
docker login ghcr.io
# Try pulling with explicit registry
docker pull ghcr.io/mrwogu/promptscript:latest

Debug Mode

Enable verbose output for troubleshooting:

Terminal window
docker run --rm \
-v $(pwd):/workspace \
-e PROMPTSCRIPT_VERBOSE=1 \
ghcr.io/mrwogu/promptscript:latest compile

Shell Access

For debugging, access the container shell:

Terminal window
docker run --rm -it --entrypoint sh ghcr.io/mrwogu/promptscript:latest

Image Details

PropertyValue
Base imagenode:25-alpine
Working directory/workspace
Usernode (UID 1000)
Entrypointnode /app/bin/prs.js
Platformslinux/amd64, linux/arm64

The image includes:

  • Node.js 25 runtime
  • Git (required for prs pull)
  • PromptScript CLI with production dependencies

See Also