@prompts-gpt/client

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/client

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

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/client 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.
• 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 | | 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

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

# 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

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.

SDK

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

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

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

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.