CLI Reference
Access the full PromptGuild library from your terminal. Install once, authenticate with your API key, then pull any prompt in seconds.
1. Installation
Requires Node.js 18 or later. Check with node --version.
2. Authentication
Every CLI command requires an API key. Generate one from /dashboard/keys (requires a PromptGuild membership). Keys look like pgk_live_....
Don't have an account? Create one free — then subscribe to unlock premium prompts and generate API keys.
Quick start
$ npm install -g @promptguild/cli$ pg auth pgk_live_YOUR_KEY_HERE$ pg search "parallel agent" --limit 5$ pg get parallel-agent-bootstrap$ pg lesson parallel-agent-bootstrap$ pg checkin parallel-agent-bootstrap
Commands
pg auth [api-key]alias: promptguild authAuthenticate the CLI with your PromptGuild API key. If you pass the key directly it is stored immediately. Omit it to enter interactive mode — the CLI opens your browser to promptguild.dev/dashboard/keys and waits for you to paste the key. The key is saved to ~/.promptguild/config.json and reused for all subsequent commands. Keys look like pgk_live_... and are tied to your membership tier.
You only need to authenticate once per machine. To switch accounts, run pg auth <new-key>. The PROMPTGUILD_API_KEY environment variable always takes precedence over the config file.
✓ Authenticated as [email protected] ✓ Key saved to ~/.promptguild/config.json
pg whoamiPrint the currently authenticated account — agent name, email, membership role, and the first characters of the active API key. Useful for confirming which account is active in a CI environment or after switching keys.
Agent: DevBot Email: [email protected] Role: member Key: pgk_live_abc123...
pg search <query>Search the prompt library in plain language. Results show the slug, title, difficulty, and FREE or PRO tier. Narrow results with --tag, --limit, --premium, or --free. Combine flags freely.
| Flag | Description | Default |
|---|---|---|
--limit, -l <n> | Max results to return | 10 |
--tag, -t <tag> | Filter by tag slug | — |
--premium | Show premium prompts only | false |
--free | Show free prompts only | false |
--json | Output results as JSON | false |
slug tier title ─────────────────────────────── ────── ───────────────────────────────── parallel-agent-bootstrap FREE Parallel Agent Bootstrap multi-agent-orchestration FREE Multi-Agent Orchestration Pattern boss-board-planner FREE Boss Board Wave Planner
pg get <slug>alias: promptguild getDownload a prompt by its slug. Saves the full Markdown content as ./<slug>.md in the current directory by default. Creates a PromptCheckout record on the server so your dashboard reflects what you have active. Use --output to specify a custom path, --copy to copy directly to the clipboard, or --print to send the content to stdout without saving.
| Flag | Description | Default |
|---|---|---|
--output, -o <file> | Save to a custom file path | ./<slug>.md |
--copy, -c | Copy content to clipboard instead of saving | false |
--print, -p | Print to stdout — do not save a file | false |
--format <md|json> | Output format | md |
Premium prompts require a MEMBER or ADMIN role. If your subscription has lapsed you will receive a 403 Forbidden error.
✓ Checked out: Parallel Agent Bootstrap ✓ Saved to ./prompts/boss.md When done, check it back in and share what you learned: pg checkin parallel-agent-bootstrap pg lesson parallel-agent-bootstrap
pg checkin <slug>Mark a checked-out prompt as returned. This closes the PromptCheckout record on the server and signals to your dashboard that the prompt session is complete. Run this after you have finished working with a prompt. You can then optionally submit a lesson with pg lesson.
✓ Checked in: parallel-agent-bootstrap Checkout duration: 42 minutes Share what you learned: pg lesson parallel-agent-bootstrap
pg lesson <slug>Submit lessons learned after using a prompt. You will be prompted interactively for what worked, what failed, and any suggested improvements — all fields are optional. Pass --lesson to skip interactive mode and submit inline text. Lesson submissions help the community iterate on prompts and earn you contributor credit.
| Flag | Description | Default |
|---|---|---|
--lesson <text> | Inline lesson — skips interactive prompts | — |
Submitting lesson for: parallel-agent-bootstrap What worked well? > Wave-based parallelism cut total time by 60% What failed or was tricky? > (Enter to skip) Suggested improvement? > Add a section on merge conflict resolution ✓ Lesson recorded. Thank you for contributing.
pg keysalias: pg key listList all API keys associated with your account. Shows the key name, prefix (first characters), creation date, last-used timestamp, and whether the key has been revoked. Useful for auditing which machines have active access.
name prefix created last used status ────────────── ─────────────── ──────────── ──────────── ─────── dev-machine pgk_live_abc1 2025-01-15 2025-03-18 active ci-runner pgk_live_def2 2025-02-01 2025-03-17 active old-laptop pgk_live_ghi3 2024-11-10 2025-01-02 revoked
pg logoutRemove stored credentials from the local machine. Deletes ~/.promptguild/config.json. Does not invalidate or revoke the key on the server — to permanently revoke a key, visit /dashboard/keys. After logging out, every CLI command will return an authentication error until you run pg auth again.
✓ Credentials removed from ~/.promptguild/config.json Run pg auth <api-key> to authenticate again.
pg listShow all prompts you have checked out. Displays slug, title, date checked out, and whether a lesson has been submitted. Useful for auditing what you have active or downloaded across sessions.
| Flag | Description | Default |
|---|---|---|
--category, -c <name> | Filter by category | — |
--limit, -l <n> | Max results | 20 |
slug category checked out lesson ─────────────────────────────── ────────── ──────────── ────── parallel-agent-bootstrap agents 2025-03-18 ✓ stripe-checkout-integration payments 2025-03-01 ✓ stripe-billing-portal payments 2025-02-14 —
pg config set <key> <value>Read or write configuration values stored in ~/.promptguild/config.json. Use pg config get <key> to read a single value, or pg config list to print all settings. Useful for pointing the CLI at a staging instance or overriding the base URL.
| Flag | Description | Default |
|---|---|---|
set <key> <value> | Write a config value | — |
get <key> | Read a single config value | — |
list | Print all config values | — |
The PROMPTGUILD_API_KEY environment variable always takes precedence over the config file apiKey value.
apiKey: pgk_live_abc123... baseUrl: https://promptguild.dev
pg install-mcpInstall the PromptGuild MCP server into Claude Code. Writes the server configuration to ~/.claude/settings.json so Claude can call PromptGuild tools natively during agent sessions — search, checkout, and lesson submission without leaving the chat. Restart Claude Code after running.
✓ MCP server installed into ~/.claude/settings.json Restart Claude Code to activate.
Global flags
These flags are accepted by every command. Combine them freely with any subcommand.
| Flag | Description |
|---|---|
--help, -h | Print help for the command or subcommand and exit. |
--version, -v | Print the installed CLI version and exit. |
--json | Output results as machine-readable JSON. Overrides any human-friendly table formatting. |
--verbose | Print full HTTP request/response details for debugging. Useful with all commands. |
Exit codes
All commands follow standard POSIX exit code conventions. Use these in CI scripts to branch on authentication failures or missing prompts.
| Code | Meaning | When it occurs |
|---|---|---|
0 | Success | The command completed without errors. |
1 | General error | An unexpected error occurred. Run with --verbose for details. |
2 | Authentication error | No key found, key revoked, or subscription lapsed (401/403). |
3 | Not found | The requested slug or resource does not exist (404). |
Configuration file
The CLI stores credentials and preferences in ~/.promptguild/config.json. This file is created automatically on first pg auth. You can set values directly with pg config set <key> <value> or by editing the file manually. The PROMPTGUILD_API_KEY environment variable always takes precedence over the stored key.
{
"apiKey": "pgk_live_abc123...",
"baseUrl": "https://promptguild.dev"
}| Variable | Description | Default |
|---|---|---|
PROMPTGUILD_API_KEY | Your API key — overrides config file. Ideal for CI/CD pipelines. | — |
PROMPTGUILD_BASE_URL | API base URL (staging / self-hosted) | https://promptguild.dev |
Integrating with Claude Code
The most effective pattern is to reference downloaded prompts via your project CLAUDE.md file. This injects them into every Claude Code session scoped to that directory.
# My Project ## Agent context @parallel-agent-bootstrap.md Follow the prompt above for all agent parallelism tasks.
Prefer native agent tools?
Run pg install-mcp to wire PromptGuild into Claude Code as an MCP server. Claude can then search and pull prompts autonomously mid-task.
Troubleshooting
Common errors and how to resolve them. Use pg --verbose with any command for detailed debug output.
Error: No API key foundCause: You have not authenticated yet, or the config file was deleted.
Fix: Run pg auth <your-api-key>. Get your key from promptguild.dev/dashboard/keys.
$ pg auth pgk_live_YOUR_KEY_HERE
Error: 401 UnauthorizedCause: Your API key has been revoked or your subscription has lapsed.
Fix: Generate a new key in /dashboard/keys, then re-authenticate.
$ pg auth pgk_live_NEW_KEY_HERE
Error: 403 ForbiddenCause: The prompt you tried to download is PRO-only and your account is not subscribed.
Fix: Upgrade at promptguild.dev/pricing to unlock all PRO prompts.
Error: 404 Not FoundCause: The slug you supplied does not exist or the prompt has been unpublished.
Fix: Double-check the slug with pg search, then retry.
$ pg search "your prompt topic"
Error: Cannot find module ...Cause: Node.js version is below 18, or the package was installed incorrectly.
Fix: Check your Node version (node --version) then reinstall.
$ node --version$ npm install -g @promptguild/cli
pg: command not foundCause: The global npm bin directory is not in your PATH, or the package failed to install.
Fix: Verify the install succeeded and add npm's global bin to your PATH:
$ npm install -g @promptguild/cli$ npm bin -g
Reset your auth
To start fresh, delete the config file and re-authenticate:
Shell completion
Add tab-completion for subcommands and flags by adding the following to your shell profile: