CLI

The Prompt Pie CLI centralizes your AI skills in one place.

When you work across different AI coding tools, each tool stores skills in its own directory. That makes skills harder to manage and keep consistent.

Prompt Pie keeps each skill in ~/.promptpie/skills/ as the source of truth, then symlinks it into the local paths used by your AI coding tools.

Before:

• add or copy a skill into Claude Code
• add or copy it again into Codex
• add or copy it again into Cursor

Now:

• add the skill once in Prompt Pie
• link it into the tools you use

Today that means:

~/.promptpie/skills/ holds the real SKILL.md file. The files in ~/.claude/skills/, ~/.agents/skills/, and ~/.cursor/skills/ are symlinks, not copies. Editing any of those paths updates the same underlying skill.

Requirements

• Node.js 18+
• npm or npx

Install

Install globally if you want the ppie command available everywhere:

npm install -g promptpie
ppie --version

The npm package is promptpie. The main command you will use is ppie.

For one-off usage without a global install:

npx promptpie --version

Setup

Run ppie init once on a machine:

ppie init

What it does:

• creates ~/.promptpie/skills/ if it does not exist
• creates ~/.claude/skills/ if it does not exist
• creates ~/.agents/skills/ if it does not exist
• creates ~/.cursor/skills/ if it does not exist

Expected output on a first run looks like this. The CLI prints absolute local paths; the sample below uses ~ for readability:

✓ Created ~/.promptpie/skills
✓ Created ~/.claude/skills
✓ Created ~/.agents/skills
✓ Created ~/.cursor/skills

Run ppie skill add <name> to create your first skill.

Running ppie init again is safe. Existing directories are left alone and reported as Already exists ....

If you previously had Prompt Pie-managed Codex links under ~/.codex/skills/, ppie init migrates those links to ~/.agents/skills/.

Basic workflow

1. Check local setup

Use status for a quick dashboard:

ppie status

Use doctor when something looks wrong:

ppie doctor

status is the fast summary. doctor is the diagnostic command for missing directories, broken links, blocked target paths, and symlinks that are not managed by Prompt Pie.

Agents can use JSON output:

ppie status --json
ppie doctor --json

2. Create a skill

ppie skill add code-review

This creates:

~/.promptpie/skills/code-review/SKILL.md

The command also prints the created path and the next suggested step.

3. Edit the skill

ppie skill edit <name> prints only the path to SKILL.md, which makes it easy to pipe into your editor:

$EDITOR "$(ppie skill edit code-review)"

4. Inspect one skill

ppie skill info code-review

This shows the source SKILL.md path and whether the skill is linked into Claude Code, Codex, and Cursor.

For agent-readable output:

ppie skill info code-review --json

5. Link the skill into your tools

Link to every supported target:

ppie skill link code-review

Or link to one target:

ppie skill link code-review claude
ppie skill link code-review codex
ppie skill link code-review cursor

Expected result:

• a symlink is created in the selected target directory
• the linked file points back to ~/.promptpie/skills/code-review/SKILL.md
• editing the skill from .promptpie, .claude, .agents, or .cursor updates the same file

Prompt Pie manages the filesystem integration. Depending on the tool, you may need to restart or reload Claude Code, Codex, or Cursor before it notices a newly linked skill.

6. See what is linked

ppie skill list

This shows each skill and where it is currently linked.

7. Import an existing markdown file

ppie skill import pull-request ./pull-request.md

This copies the file into:

~/.promptpie/skills/pull-request/SKILL.md

8. Preview risky changes

Use --dry-run to preview supported risky changes without touching the filesystem:

ppie skill link code-review codex --dry-run
ppie skill link code-review codex --force --dry-run
ppie skill unlink code-review codex --dry-run
ppie skill rm code-review --dry-run

Dry runs validate inputs and show what would happen. They do not create, replace, unlink, or remove files. If a link or unlink dry-run is blocked, it exits 1 and JSON output uses ok: false.

9. Unlink or remove

Remove only the symlink from one target:

ppie skill unlink code-review codex

This removes only the target link. It does not delete the source skill in ~/.promptpie/skills/.

Remove the skill entirely, including all of its links:

ppie skill rm code-review

Agent-facing examples

ppie is designed to be useful from an AI agent terminal session.

Examples:

• "Use ppie status --json to check my Prompt Pie setup."
• "Use ppie doctor --json and tell me why Codex cannot see this skill."
• "Show me where code-review is linked."
• "Dry-run linking code-review into Codex and Claude Code before changing anything."

Useful commands for agents:

ppie status --json
ppie doctor --json
ppie skill info code-review --json
ppie skill link code-review codex claude --dry-run --json

Global options

--dry-run is supported for:

• ppie skill rm <name>
• ppie skill remove <name>
• ppie skill link <name> [targets...]
• ppie skill unlink <name> [targets...]

Command reference

Troubleshooting

Start with:

ppie status

If it reports issues, run:

ppie doctor

Common fixes:

• Missing directories: run ppie init
• Skill not visible in one tool: run ppie skill info <name>
• Target path blocked by an existing file: preview with ppie skill link <name> <target> --force --dry-run
• Broken or foreign symlink: run ppie doctor, preview the suggested command, then decide whether to repair with --force

Naming rules

Skill names:

• must start with a letter or number
• can include letters, numbers, hyphens, underscores, and dots
• must be 64 characters or fewer

Examples:

• valid: code-review, pr_helper, react.v2
• invalid: .hidden, ../hack, foo/bar