Synced from promptargs. This page is pulled from hivecommons/promptargs@main during the docs build. Edit the canonical source in the promptargs repository.

promptargs 🏴‍☠️

Template arguments for AI prompts.

You write a prompt with blanks (“), and promptargs fills them in.

Review  for  issues.

becomes…

Review src/app.ts for security issues.

That’s it. That’s the whole idea.

Works as a CLI and as a skill in Claude Code, Copilot, Goose, and Bob.

Install

Requires Node.js 22 or newer.

CLI

npm install -g @hivecommons/promptargs

Or just run it without installing:

npx @hivecommons/promptargs help

As a Slash Command / Skill

This repo ships skill files for multiple AI coding tools. Install the(s) you use:

Claude Code:

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/promptargs.md \
  https://raw.githubusercontent.com/hivecommons/promptargs/main/.claude/commands/promptargs.md

Goose:

mkdir -p ~/.config/goose/skills
curl -o ~/.config/goose/skills/promptargs.md \
  https://raw.githubusercontent.com/hivecommons/promptargs/main/.goose/agents/promptargs.md

Bob (IBM):

mkdir -p ~/.bob/skills
curl -o ~/.bob/skills/promptargs.md \
  https://raw.githubusercontent.com/hivecommons/promptargs/main/.bob/skills/promptargs.md

Copilot: Automatically detected from .github/copilot-instructions.md when you clone this repo.

Quick Start (3 steps)

Step 1: Make some templates

promptargs init

This creates a .prompts/ folder with 3 starter templates. Done!

Step 2: See what you have

promptargs list

Available templates:

  review
    vars:     

  explain
    vars:     

  fix
    vars:       

Step 3: Use a template

promptargs review --file=src/app.ts

Review src/app.ts for correctness issues.
Be concise in your feedback.
Focus on real bugs, not style nitpicks.

Variables with =something already have a default. Variables without will ask you to fill them in.

How Blanks Work

Powered by Mustache — a logic-less template language available in every major language.

A blank looks like this: “

A blank with a default looks like this: “ (promptargs extension)

Padding inside the braces is fine too — and mean the same thing.

That’s the basics. Mustache comments (“) work as documented and are safe to use.

Mustache sections (...) and partials () are parsed too, but aren't practically usable yet: promptargs resolves plain / tags from `--flag=value`, auto-detected context, defaults, or interactive fill — a section's condition name is never filled this way (so its content is always dropped, or always kept for an inverted section), and partial content is never supplied, so “ always expands to nothing. Stick to plain blanks and comments; avoid sections and partials for now.

Red means “you need to fill this in”

promptargs show review

Shows the template with red blanks (required) and yellow blanks (has a default).

Fill Blanks Your Way

From the command line

promptargs review --file=main.go --focus=security --tone=detailed

Interactively (just run it, it asks you)

promptargs review
  file: main.go
  focus: (correctness)     ← press Enter to keep default
  tone: detailed

Inline (no template file needed)

promptargs "Explain  to a " --thing=recursion

Explain recursion to a 5-year-old

The Fun Part: Arrays! 🎰

Want to review 5 files? Don’t run the command 5 times. Use a comma:

promptargs review --file=api.go,auth.go,db.go,cache.go,main.go

promptargs runs the template once for each value and prints each expanded result separated by ---:

Review api.go for correctness issues.
Be concise in your feedback.
Focus on real bugs, not style nitpicks.
---
Review auth.go for correctness issues.
Be concise in your feedback.
Focus on real bugs, not style nitpicks.
---
Review db.go for correctness issues.
...

Status lines showing iteration progress go to stderr:

✅ review [1/5]: file=api.go    focus=correctness  tone=concise
✅ review [2/5]: file=auth.go   focus=correctness  tone=concise
...

Three ways to pass arrays

Multiple arrays: zip vs cross-product

Zip mode (default): arrays pair up 1:1:

promptargs "Review  for " \
  --file=api.go,auth.go,db.go \
  --focus=security,perf,correctness

✅ [1/3]: file=api.go   focus=security
✅ [2/3]: file=auth.go  focus=perf
✅ [3/3]: file=db.go    focus=correctness

Cross-product mode (--cross): every combination of every value:

promptargs "Review  for " \
  --file=api.go,auth.go,db.go \
  --focus=security,perf,correctness \
  --cross

✅ [1/9]: file=api.go   focus=security
✅ [2/9]: file=api.go   focus=perf
✅ [3/9]: file=api.go   focus=correctness
✅ [4/9]: file=auth.go  focus=security
✅ [5/9]: file=auth.go  focus=perf
✅ [6/9]: file=auth.go  focus=correctness
✅ [7/9]: file=db.go    focus=security
✅ [8/9]: file=db.go    focus=perf
✅ [9/9]: file=db.go    focus=correctness

3 files × 3 focuses = 9 runs. Use --cross when you want the full matrix.

Where Templates Live

Project templates override personal with the same name.

Auto-Magic Variables ✨

promptargs discovers variables from two sources:

Run promptargs env any time to preview exactly what’s auto-detected in your current shell before you run a template:

promptargs env

1. Git context (always detected)

These variable names fill themselves automatically when you’re in a git repo:

2. Terminal environment (any env var)

Any environment variable in your terminal is available as a template variable. Use the same name:

# If your terminal has DATABASE_URL and AWS_REGION set:
promptargs "Connect to  in "

In the Builder UI (promptargs ui), click “Show terminal env” to see all available env vars from your shell. Click any to insert it at the cursor.

Common useful env vars: NODE_ENV, AWS_REGION, CI, USER, EDITOR, PATH, SHELL.

Credential-looking names are intentionally excluded from auto-detection: anything containing TOKEN, SECRET, PASSWORD/PASSWD/PASSPHRASE, CREDENTIAL, API_KEY/ACCESS_KEY/PRIVATE_KEY, BEARER, COOKIE, WEBHOOK, JWT, HMAC, OAUTH, CONNECTION_STRING, or the _-delimited words AUTH, KEY/KEYS, PWD, PAT, PASS, DSN (so GITHUB_TOKEN, SIGNING_KEY, MYSQL_PWD, GITHUB_PAT and SLACK_WEBHOOK_URL are all refused, while PATH, PWD, KEYBOARD and AUTHOR still work). Credential-shaped values are excluded whatever the name: URLs with a password in them (postgres://user:pass@host/db), PEM blocks, JWTs, and well-known token prefixes (ghp_, github_pat_, glpat-, sk-, xoxb-, AKIA…, npm_…, …). A repo-controlled template can therefore never expand or into a secret, even though an explicit --flag=value can still pass any value you choose. This also applies to the Builder UI’s “Show terminal env” list.

Priority

You can always override any auto-detected value with a flag. The order is:

1. --flag=value (explicit, always wins)
2. Auto-detect from environment (git context and terminal env vars)
3. Template default (“)
4. Interactive prompt — for variables still unfilled, and without --no-interactive

A variable that auto-detects or has a default is never prompted for; pass --name=value to override it.

Output Formats

Plain text (default)

promptargs review --file=main.go

JSON

promptargs review --file=main.go --json

Status line (for IDE integration)

promptargs review --file=main.go --status

✅ review: file=main.go  focus=correctness(default)  tone=concise(default)

Builder UI

Don’t want to memorize flags? Open the visual builder:

promptargs ui

Opens a browser at http://localhost:3700 with:

• Preset examples — 8 clickable templates (review, explain, fix, test, migrate, security, docs, refactor)
• Template editor — type your template, variables auto-populate below
• Variable table — set values, arrays (comma-separated), and sources (manual, glob, @file)
• Environment panel — git context vars + all terminal env vars, click any to insert “ at cursor
• Mustache cheatsheet — collapsible syntax reference for template features
• Zip / Cross toggle — switch array iteration mode
• Live preview — see expanded output update as you type
• CLI command — copy the generated command with click

Use --port=N if 3700 is taken:

promptargs ui --port=4000

Privacy & Diagnostics

promptargs does not collect or export telemetry. There is no telemetry SDK, metrics endpoint, or observability backend configured anywhere in this package — nothing you run ever phones home.

All runtime diagnostics are human-readable console output (CLI status/errors, UI startup/port messages). The Builder UI (promptargs ui) binds to loopback (127.0.0.1) and rejects requests with a non-local Host header, so the page — including the auto-detected Git and terminal environment values it embeds (see Auto-Magic Variables) — is never reachable from other machines on your network.

If observability is ever added in the future, it will be explicit opt-in, bounded to local diagnostics, and will exclude environment values, template/prompt content, file paths, diffs, and user identifiers. No network exporter will be added unless you explicitly configure a backend yourself.

Write Your Own Template

Create a file in .prompts/ with any name ending in .md:

.prompts/buddy.md

Hey ! Can you help me understand ?
I learn best with .

Now use it:

promptargs buddy --topic="async/await"

Hey buddy! Can you help me understand async/await?
I learn best with examples and analogies.

Use with AI Coding Tools

Pipe to any CLI

promptargs works with any AI tool that accepts piped input:

# Claude
promptargs review --file=src/main.ts --no-interactive | claude -p "do this review"
 
# Goose
promptargs review --file=src/main.ts --no-interactive | goose run
 
# Copilot CLI (needs the standalone `copilot` CLI, installed and signed in)
copilot -p "$(promptargs review --file=src/main.ts --no-interactive)"

As a skill inside your AI tool

If you installed the skill (see Install), use it directly inside your session:

Claude Code:

/promptargs review --file=src/api.ts

Goose / Bob: The skill is automatically available after install — ask your agent to “use promptargs” or run a template.

Copilot: The instructions in .github/copilot-instructions.md teach Copilot about promptargs when you’re in a repo that has it.

Cheat Sheet

License

Apache-2.0

Pirate flag icon: Twemoji, CC-BY 4.0.