prompts-gpt

CLI and SDK for syncing Prompts-GPT prompt packs into any project — with integrations for Codex, Claude Code, Cursor, VS Code, GitHub Copilot, Continue, Gemini CLI, Windsurf, Cline, Junie, and Amp.

Get Started

# Install
npm install -D prompts-gpt

# Interactive setup — handles credentials, config, and shows runnable commands
npx prompts-gpt quickstart

On Windows PowerShell, prefer npm exec because it resolves the local workspace bin more reliably than npx:

npm exec prompts-gpt -- quickstart
npm exec prompts-gpt -- init
npm exec prompts-gpt -- sweep

Or step by step:

npx prompts-gpt init                  # save your project token (prompts interactively)
npx prompts-gpt sync                  # pull prompts and write agent files
npx prompts-gpt list                  # see what's available
npx prompts-gpt run                   # execute a single prompt
npx prompts-gpt sweep                 # run a multi-iteration sweep

Requires Node.js 18.18+.

What It Does

Bridges the Prompts-GPT cloud library with the agent instruction files each tool reads:

| Agent | Written files | |-------|--------------| | Codex | AGENTS.md | | Claude Code | CLAUDE.md | | Cursor | .cursor/rules/*.mdc + .cursor/commands/*.md | | VS Code | .github/copilot-instructions.md + .vscode/*.code-snippets | | Copilot | .github/prompts/*.prompt.md | | Continue | .continue/rules/*.md | | Gemini CLI | GEMINI.md | | Windsurf | .windsurf/rules/*.md | | Cline | .clinerules/*.md | | Junie | .junie/guidelines.md | | Amp | AGENT.md |

Important Use Notes

• prompts-gpt is the published npm package. If you see examples that reference internal app modules such as lib/sdk, those are app-internal examples, not the public package import path.
• If Windows shows Unknown command: quickstart or Unknown command: sweep while prompts-gpt is installed, run npm exec prompts-gpt -- help or node .\\node_modules\\prompts-gpt\\dist\\cli.js help to confirm the local bin is being used instead of a stale shell shim.
• Local orchestration can send prompt text, code context, and repository files to third-party model providers and agent CLIs. Review each provider's terms, privacy settings, and permitted automation paths before using private or regulated data.
• Run artifacts are written locally and can include prompts, model output, logs, and worktree snapshots. Treat .scripts/runs as sensitive and do not commit or share it casually.

CLI Commands

| Command | Description | |---------|-------------| | quickstart | Interactive setup — credentials, config, and first run | | init | Save project token (prompts interactively if no flags given) | | setup | Scaffold local orchestration config | | sync | Pull + generate + write agent files | | pull | Download prompt packs as Markdown files | | generate | Generate a prompt pack from a goal | | load-config | Pull full config from Prompts Studio | | run | Execute one prompt with a local agent (-f <file>) | | run-batch | Execute multiple prompts | | sweep | Multi-iteration execution (-f <file> -n <count>) | | list | Show prompts, sweeps, agents | | status | Show workspace readiness | | providers | Show detected CLIs | | doctor | Validate prerequisites | | validate | Check config for errors | | models | List known models per provider | | sync-models | Fetch latest model registry from prompts-gpt.com | | project | Show the current project linked to the token |

Run prompts-gpt help <command> for detailed options.

Examples

# Run a single prompt (auto-selects if only one exists)
prompts-gpt run -f .prompts-gpt/review.md --agent cursor

# Run a sweep (auto-detects local sweeps, reads iterations from frontmatter)
prompts-gpt sweep
prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 5

# Run every sweep file sequentially or in parallel
prompts-gpt sweep --all-sweeps --sweep-strategy sequential
prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3 -n 2

# Run only selected sweep files
prompts-gpt sweep --sweep-files design,research --sweep-strategy parallel -n 2
prompts-gpt sweep --sweep-files .prompts-gpt/sweeps/design.md,.prompts-gpt/sweeps/research.md --sweep-strategy sequential

# Preview what a sweep would do
prompts-gpt sweep --dry-run

# Run and score multiple providers on one prompt
prompts-gpt orchestrate --mode parallel -f .prompts-gpt/review.md --providers codex,claude,cursor --criteria correctness,completeness

# Interactive orchestration mode picker
prompts-gpt orchestrate

# Chain steps with context passing
cat > pipeline.json <<'EOF'
[
  {"name":"research","promptFile":".prompts-gpt/review.md","agent":"codex"},
  {"name":"implement","promptFile":".prompts-gpt/review.md","agent":"claude"},
  {"name":"review","promptFile":".prompts-gpt/review.md","agent":"cursor"}
]
EOF
prompts-gpt orchestrate --mode pipeline --steps pipeline.json --dry-run

# Run once and evaluate with explicit criteria
prompts-gpt orchestrate --mode eval -f .prompts-gpt/review.md --criteria correctness,risk,clarity
prompts-gpt orchestrate --mode eval --dry-run --eval-criteria correctness,risk,clarity

# Inspect available models for the resolved orchestration providers
prompts-gpt orchestrate --mode eval --list-models

# Re-run a prompt when the file changes
prompts-gpt run -f .prompts-gpt/review.md --watch

# Scaffold local runner config and prompt sources
prompts-gpt doctor --fix

# Inspect the worktree delta for a recent run
prompts-gpt diff
prompts-gpt diff <run-id>

# Run a sweep with reduced output
prompts-gpt sweep --quiet

# Run one sweep file with independent parallel iterations
prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 6 --parallel 3

# List available models for a provider
prompts-gpt models --provider codex

# Sync model registry from cloud
prompts-gpt sync-models

# Use canonical model names only
prompts-gpt run --agent claude --model claude-opus-4-7
prompts-gpt run --agent cursor --model claude-4.6-opus-high
prompts-gpt run --agent codex --model gpt-5.4-mini
prompts-gpt run --agent codex --model gpt-5.5

# Sync from cloud
prompts-gpt sync --agent all

# Generate a prompt pack from a goal
prompts-gpt generate --goal "Review PRs for security issues" --sync-agents

# CI/CD — pipe token from secret
printf '%s' "$PROMPTS_GPT_TOKEN" | prompts-gpt sync --token-stdin --agent all

Sweep Use Cases

Sweeps live in .prompts-gpt/sweeps/*.md. By default, prompts-gpt sweep auto-selects the local sweep when there is only one, or prompts you to choose when multiple sweeps exist.

Use these modes when you want explicit control over which sweep files run and how iterations are scheduled:

| Use case | Command | |----------|---------| | Run the default or selected single sweep | prompts-gpt sweep | | Run one sweep file for a fixed number of iterations | prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 5 | | Run one sweep file with iterations in parallel | prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 6 --parallel 3 | | Run every sweep file sequentially | prompts-gpt sweep --all-sweeps --sweep-strategy sequential | | Run every sweep file sequentially with the same iteration count per file | prompts-gpt sweep --all-sweeps --sweep-strategy sequential -n 2 | | Run every sweep file in parallel | prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3 | | Run every sweep file in parallel with repeated iterations per file | prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3 -n 2 | | Run selected sweep files sequentially by name | prompts-gpt sweep --sweep-files design,research --sweep-strategy sequential | | Run selected sweep files sequentially by path | prompts-gpt sweep --sweep-files .prompts-gpt/sweeps/design.md,.prompts-gpt/sweeps/research.md --sweep-strategy sequential | | Run selected sweep files in parallel | prompts-gpt sweep --sweep-files design,research --sweep-strategy parallel --file-concurrency 2 | | Run selected sweep files in parallel with repeated iterations per file | prompts-gpt sweep --sweep-files design,research --sweep-strategy parallel --file-concurrency 2 -n 3 | | Preview the selected sweep plan without launching providers | prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3 --dry-run | | Run and score each sweep iteration | prompts-gpt sweep --all-sweeps --eval --eval-criteria correctness,risk,clarity |

Key scheduling rules:

• --sweep-strategy sequential runs selected sweep files one after another. This is the safest default when sweeps may edit overlapping files.
• --sweep-strategy parallel runs multiple sweep files at the same time. Use --file-concurrency <n> to cap how many files run concurrently.
• --parallel <n> controls parallel iterations inside a single sweep file. It is separate from --file-concurrency.
• -n, --iterations <count> overrides the frontmatter iterations: value for every selected sweep file.
• When -n is omitted, each sweep file uses its own frontmatter iterations: value, falling back to 1.
• --sweep-files accepts comma-separated sweep names, filenames, or paths. For example, design, design.md, and .prompts-gpt/sweeps/design.md can all resolve the same file.
• --all-sweeps cannot be combined with --sweep-files, and multi-file selection cannot be combined with -f, --prompt-file.
• --files-mode sequential|parallel is accepted as an alias for --sweep-strategy sequential|parallel.

Practical recommendations:

• Use sequential all-sweeps for broad repo QA where each sweep may write code.
• Use parallel selected sweeps for independent areas such as docs, tests, and marketing copy.
• Use single-file --parallel when you want competing iterations of the same prompt, then compare outputs.
• Use --dry-run before large parallel runs to verify file selection, iteration counts, and concurrency.
• Keep --file-concurrency modest when sweeps call paid providers or local agents that consume heavy CPU.

Configuration

Create .prompts-gpt/config.json via prompts-gpt setup, or manually:

{
  "providerOrder": ["codex", "cursor", "claude", "copilot"],
  "defaultAgent": "router",
  "timeoutSeconds": 900,
  "artifactsDir": ".scripts/runs"
}

All options can be overridden via environment variables. See prompts-gpt help setup.

Orchestration Patterns

• parallel: run multiple providers against the same prompt, score outputs, and report the strongest result with local logs and diffs.
• pipeline: pass context across named steps when research, implementation, and review should be separated.
• eval: run one provider and force a structured quality score for the output.
• eval --dry-run: if -f is omitted, the CLI uses the first discovered .prompts-gpt prompt so workspace scaffolds can verify orchestration immediately.
• sweep --eval --eval-criteria correctness,completeness,...: add self-evaluation after each successful iteration.
• diff <run-id>: inspect the stored worktree delta from a prior run.
• run --watch: rerun automatically when the prompt file changes.
• doctor --fix: scaffold .prompts-gpt/config.json, detect prompt sources, and add the artifacts directory to .gitignore.

Visibility implementation workflow

Use orchestration after a monitor or checker identifies a concrete gap:

1. Export the prompt, answer evidence, cited URLs, and desired fix from Prompts-GPT.com.
2. Run prompts-gpt orchestrate --mode parallel when multiple agents should propose competing fixes.
3. Run prompts-gpt orchestrate --mode pipeline when research, implementation, and review should stay separated.
4. Run prompts-gpt orchestrate --mode eval or prompts-gpt sweep --eval --eval-criteria correctness,risk,clarity when output quality needs a score.
5. Run prompts-gpt diff <run-id> before sharing the worktree changes.

Dry-runs verify command wiring, prompt resolution, evaluator selection, and criteria parsing without launching a provider:

npx prompts-gpt orchestrate --mode eval --dry-run --eval-criteria correctness,risk,clarity

Full pattern guide (parallel vs pipeline vs eval, visibility handoff, diff/watch): docs/orchestration-patterns.md in the main repo.

SDK

import { PromptsGptClient, syncPrompts } from "prompts-gpt";

const client = new PromptsGptClient({
  token: "pgpt_your_token",
  apiUrl: "https://prompts-gpt.com",
  fetch,
});

const prompts = await client.pullPrompts();
await syncPrompts(prompts, { agent: "all" });

// Fetch available models per provider
const models = await client.fetchModels();
// Filter by provider
const codexModels = await client.fetchModels({ provider: "codex" });

Data Privacy

What stays local:

• .prompts-gpt/*.md prompt files are written locally
• Agent files (AGENTS.md, .cursor/rules/, etc.) are updated locally
• Run artifacts (.scripts/runs/) including logs, diffs, and summaries stay local
• No local files, repo content, or uncommitted changes are uploaded

What is sent to prompts-gpt.com:

• prompts-gpt generate --goal ... — the text you explicitly pass via --goal, --context, and --constraints flags is sent to the API for AI-powered prompt generation
• prompts-gpt sync --goal ... — same as above when --goal is used
• prompts-gpt pull / sync / load-config — your project token is sent to authenticate and download prompts from your library

Do not include PII, secrets, or confidential data in --goal, --context, or --constraints flags. Use --dry-run with sync to preview what would be sent.

Security

• Credentials stored with 0600 permissions
• Credentials added to .gitignore
• Token prefix (pgpt_) validated before requests
• HTTPS enforced for non-localhost
• Path traversal blocked for all file writes
• Secret patterns (pgpt_, sk-, ghp_) are redacted from API-bound input, command previews, and error output
• SIGINT/SIGTERM cleanup releases locks
• Run artifact directories are intended to stay local and may contain sensitive prompt, output, and diff data

License

Prompts-GPT Source Available License — free for personal and commercial use. Redistribution and modification of the package are not permitted.