Promptrix CLI

🚀 Score and improve every prompt in your codebase — from your terminal

Promptrix CLI optimizes a single prompt, or finds and scores every prompt in a repository — prompt files, agent context files like CLAUDE.md and AGENTS.md, and system prompts embedded in your source code.

🎯 Features

• Repo-aware: Discover and score every prompt in a project, not one at a time
• Works offline: Scoring is deterministic and runs entirely on your machine — no API key, no network
• Safe by default: Every rewrite is shown as a diff, backed up, and reverted if it lowers the score
• CI-ready: promptrix score --min 50 fails a build when prompt quality regresses
• Instant Optimization: Transform any prompt into a more effective version
• Advanced Methods: 22 optimization methods with category and complexity filtering
• Multi-Model Support: Optimize for specific AI models (GPT-4, Claude, Gemini, etc.)
• Pipe Support: Integrate seamlessly with Unix tools and scripts

📦 Installation

npm install -g promptrix-cli

The npm package is promptrix-cli; the command it installs is promptrix. Bare npx promptrix resolves to an unrelated package on npm and will not work — use npx promptrix-cli for a one-off run:

npx promptrix-cli "Your prompt here"

🔑 Authentication

scan, score, status, bootstrap and undo need no API key — they run entirely on your machine. Only improve, insights and single-prompt optimization call the API.

Get your API key:

1. Visit https://promptrix.co/developers
2. Sign up for a free account
3. Copy your API key
4. Configure the CLI:

promptrix config --key your-api-key-here

Alternatively, set via environment variable:

export PROMPTRIX_API_KEY=your-api-key-here

🗂️ Working on a repository

Point the CLI at a project and it finds every prompt in it:

promptrix scan     # list every prompt found, with its location
promptrix score    # score them all 0-100, with a per-check breakdown

Both run entirely on your machine — no API key, no network request, nothing uploaded.

What gets discovered

| Kind | Where | |------|-------| | Prompt files | prompts/**, *.prompt, .github/prompts/** | | Agent context files | CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc, copilot-instructions.md | | Embedded prompts | system prompts in your source — role: 'system', system: parameters, prompt templates |

Improving them

promptrix improve                       # review each proposed change as a diff
promptrix improve prompts/review.md     # a single file
promptrix improve --yes                 # apply without prompting
promptrix undo                          # restore the previous version

improve never writes without showing you the diff first. Every write is backed up, a rewrite that would lower the score is rejected automatically, and prompts embedded in source files are read-only unless you pass --write-embedded.

Using it in CI

Because scoring needs no credentials and is deterministic, it works as a build gate:

promptrix score --min 50   # exit non-zero if any prompt scores below 50
promptrix score --json     # machine-readable output

--json prints paths, scores and failed check ids — a stable, lean shape meant for pipelines. Adding --verbose swaps it for the full report payload instead:

promptrix score --json --verbose --include-text > report.json

That carries everything the hosted dashboard shows for a project — per-category breakdowns, every check with its detail and suggestion, a paste-ready brief for a coding agent, and (under --include-text) the prompt bodies — all computed locally, with no account and no network call. The payload is versioned by schemaVersion; read it before parsing the rest.

Teaching your agent to use it

promptrix bootstrap

Writes a Promptrix skill into .claude/skills/, .cursor/skills/ or .agents/skills/ so Claude Code and Cursor know how to score and improve the prompts in your repo.

For Claude Code specifically there is also a plugin, which turns that payload into an HTML report written into your repo:

/plugin marketplace add pupik1989/promptrix-plugin
/plugin install promptrix@promptrix
/promptrix:report

Tracking quality over time

promptrix status            # counts, average score and trend
promptrix insights          # score history and per-method effectiveness
promptrix score --publish   # send paths and scores to your dashboard (opt-in)
promptrix scan --publish --include-text   # also send the prompt bodies

--publish transmits file paths and scores; prompt text is transmitted only if you add --include-text, which unlocks the dashboard's per-prompt view with its full breakdown and suggestions.

📖 Usage

Basic Optimization

promptrix "Explain quantum computing"

Target Specific Models

# Optimize for GPT-4
promptrix "Write a Python function" --target gpt-4

# Optimize for Claude
promptrix "Analyze this text" --target claude-3

# Optimize for Gemini
promptrix "Create a story" --target gemini

Style Options

# Concise output
promptrix "Summarize machine learning" --style concise

# Detailed explanation
promptrix "Explain Docker" --style detailed

# Creative writing
promptrix "Write a story opening" --style creative

# Technical documentation
promptrix "Document this API" --style technical

Pipe from Files or Commands

# From file
cat prompt.txt | promptrix

# From another command
echo "Explain this concept" | promptrix

# Chain with other tools
promptrix "Generate SQL query" | mysql database

JSON Output

promptrix "Your prompt" --format json

Output:

{
  "improvedPrompt": "...",
  "improvements": ["..."],
  "confidence": 0.95
}

Check Usage

promptrix usage

Output:

📊 Promptrix Usage Stats
━━━━━━━━━━━━━━━━━━━━━━
  Used: 42 / 100 (42%)
  Remaining: 58
  Resets: 01/01/2024

Optimization Methods

List available optimization methods:

promptrix methods

Output with enhanced metadata:

🔧 Available Optimization Methods
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Available: 22 methods

✅ Available Methods:
  🧠 Chain of Thought
    Adds systematic reasoning steps to prompts
    ⭐ Basic • 🧠 Reasoning & Analysis • ⏱️  5-15s
    Use: promptrix "prompt" --method CHAIN_OF_THOUGHT

  ✅ Chain-of-Verification
    Reduces hallucinations by adding fact-checking
    ⭐⭐ Intermediate • 🔍 Verification & Quality • ⏱️  15-30s
    Use: promptrix "prompt" --method CHAIN_OF_VERIFICATION

💡 Tip: Filter methods with --category or --complexity flags

Filter Methods by Category

# Show only verification methods
promptrix methods --category verification

# Show only reasoning methods
promptrix methods --category reasoning

# Available categories:
# - verification: Reduce hallucinations, improve accuracy
# - reasoning: Systematic thinking, multi-perspective analysis
# - structure: Organize output, format responses
# - learning: Learn from examples, improve patterns
# - planning: Break down complex tasks, strategize

Filter Methods by Complexity

# Show only basic methods (fast, simple)
promptrix methods --complexity basic

# Show only advanced methods (complex, thorough)
promptrix methods --complexity advanced

# Complexity levels:
# - basic: ⭐ Quick optimization (5-15s)
# - intermediate: ⭐⭐ Balanced approach (15-30s)
# - advanced: ⭐⭐⭐ Deep optimization (25-45s)

Combine Filters

# Find advanced reasoning methods
promptrix methods --category reasoning --complexity advanced

# Find basic verification methods
promptrix methods --category verification --complexity basic

Use Advanced Methods

# Apply specific optimization method
promptrix "Explain blockchain" --method CHAIN_OF_VERIFICATION

# Use expert panel method for multiple perspectives
promptrix "Design a system" --method EXPERT_PANEL_SIMULATOR

🛠️ Advanced Usage

Configuration File

The CLI stores configuration in ~/.promptrix/config.json:

{
  "apiKey": "your-key",
  "defaultStyle": "concise",
  "defaultTargetModel": "gpt-4",
  "analytics": true
}

Scripting Example

#!/bin/bash
# optimize_prompts.sh

for file in prompts/*.txt; do
  optimized=$(cat "$file" | promptrix --quiet)
  echo "$optimized" > "optimized/$(basename "$file")"
done

CI/CD Integration

# GitHub Actions Example
- name: Optimize prompts
  run: |
    npm install -g promptrix-cli
    promptrix "Deploy message" > deploy_message.txt
  env:
    PROMPTRIX_API_KEY: ${{ secrets.PROMPTRIX_API_KEY }}

🎨 Command Reference

| Command | Description | Needs API key | |---------|-------------|---------------| | promptrix [prompt] | Optimize a prompt | yes | | promptrix bootstrap | Install Promptrix skills for Claude Code / Cursor | no | | promptrix scan | List every prompt found in the project | no | | promptrix score [path] | Score prompts 0-100 with a per-check breakdown | no | | promptrix improve [path] | Rewrite weak prompts, reviewing each diff | yes | | promptrix undo | Restore the most recent backup | no | | promptrix status | Prompt counts, average score and trend | no | | promptrix insights | Score history and per-method effectiveness | yes | | promptrix methods | List optimization methods | yes | | promptrix methods --category <cat> | Filter methods by category | yes | | promptrix methods --complexity <level> | Filter methods by complexity | yes | | promptrix methods show <name> | Show method details | yes | | promptrix --help | Show help message | no | | promptrix --version | Show version | no | | promptrix config --key <key> | Set API key | no | | promptrix usage | Check usage stats | yes |

Options

| Option | Description | Example | |--------|-------------|---------| | --method <name> | Use specific optimization method | --method CHAIN_OF_VERIFICATION | | --target <model> | Target AI model | --target gpt-4 | | --style <style> | Output style | --style concise | | --level <level> | Complexity level | --level expert | | --format <format> | Output format | --format json | | --lang <language> | Output language | --lang es | | --quiet | Suppress decorative output | --quiet | | --no-analytics | Disable anonymous telemetry | --no-analytics |

Project Options (for scan, score, improve)

| Option | Description | Example | |--------|-------------|---------| | --root <dir> | Project directory | --root ../other-repo | | --json | Machine-readable output | --json | | --verbose, -v | Per-check breakdown for every prompt; with --json, the full report payload | --verbose | | --min <n> | Exit non-zero if any prompt scores below n | --min 50 | | --below <n> | Only improve prompts scoring below n | --below 50 | | --limit <n> | Cap how many prompts are sent in one run | --limit 5 | | --yes | Apply changes without interactive review | --yes | | --write-embedded | Allow rewriting prompts inside source files | --write-embedded | | --publish | Send paths and scores to your dashboard | --publish | | --include-text | With --publish, also send the prompt bodies; with --json --verbose, carry them locally | --include-text |

Method Filter Options (for promptrix methods command)

| Option | Description | Values | |--------|-------------|--------| | --category <cat> | Filter by category | verification, reasoning, structure, learning, planning | | --complexity <level> | Filter by complexity | basic, intermediate, advanced |

💡 Examples

Development Workflows

# Optimize code documentation
promptrix "Document this function: $(cat function.js)"

# Generate commit messages with verification method
git diff | promptrix "Write commit message for these changes" --method CHAIN_OF_VERIFICATION

# Create test cases with expert panel method
promptrix "Generate test cases for login function" --method EXPERT_PANEL_SIMULATOR

# Find methods suitable for code tasks
promptrix methods --category structure --complexity basic

Content Creation

# Blog post outline
promptrix "Create blog outline about AI trends" --style detailed

# Social media posts
promptrix "Tweet about product launch" --style creative --target gpt-4

# Email templates
promptrix "Customer support email for refund request" --style professional

Data & Analysis

# SQL queries
promptrix "Query to find top customers by revenue" --style technical

# Data analysis
cat data.csv | head -10 | promptrix "Analyze this data pattern"

# RegEx patterns
promptrix "Regex to match email addresses" --format json

🚀 Pro Tips

1. Save commonly used prompts: Create aliases for frequent optimizations

   alias commit-msg='git diff | promptrix "Write commit message"'

2. Batch processing: Process multiple files efficiently

   find . -name "*.prompt" -exec promptrix {} \;

3. Integration with AI tools: Pipe optimized prompts directly to AI CLIs

   promptrix "Your prompt" | gpt-cli

4. Version control prompts: Track prompt evolution in git

   promptrix "Initial prompt" > prompts/v1.txt
   git add prompts/v1.txt

📈 Limits

Every account gets the same limits — there are no tiers:

• 10,000 optimizations per month (resets on the 1st)
• 100 requests per minute
• Up to 10 API keys

Local commands (scan, score, status, bootstrap, undo) never call the API, so they do not count against any of this.

🔗 Links

• Documentation
• API Reference
• GitHub Issues
• Web Dashboard

📝 License

Copyright © 2024 Promptrix Inc. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, modification, or distribution is strictly prohibited. See Terms of Service for details.

🤝 Support

Need help? We're here for you:

• 📧 Email: [email protected]
• 🐛 Issues: Report on GitHub

Made with ❤️ by the Promptrix team