prompts-gpt run

Execute a single prompt file with a local AI agent and write run artifacts.

Usage

prompts-gpt run [-f <path>] [--agent <name>] [--model <name>] [--timeout <seconds>] [--dry-run]

When to Use

Use run for single-shot prompt execution — one prompt, one pass, no iteration. The agent reads the prompt, executes it, and writes artifacts to the run directory.

If you need:

Multiple prompts → use <code>run-batch</code>
Multi-iteration with context chaining → use <code>sweep</code>
Multi-provider comparison → use <code>orchestrate --mode parallel</code>

Options

Flag	Description
`-f, --prompt-file <path>`	Prompt file path. Auto-selects if only one exists locally.
`--agent <name>`	Orchestration profile: `codex`, `claude`, `cursor`, `copilot`, or `router`. Default from config or `router`.
`--model <name>`	Model override for the selected provider.
`--timeout <seconds>`	Execution timeout in seconds.
`--artifacts-dir <path>`	Override run artifacts directory.
`--run-id <id>`	Explicit run ID for artifact folder naming.
`--sandbox <mode>`	Codex sandbox mode. Default: `workspace-write`.
`--no-approve-mcps`	Disable Cursor MCP auto-approval flag.
`--background`	Run as a background agent (Cursor cloud agent mode).
`--permission-mode <mode>`	Claude Code permission mode. Default: `acceptEdits`.
`--dry-run`	Preview execution parameters without running.
`--non-interactive`	Skip all interactive prompts (same as CI mode).
`--json`	Print machine-readable JSON output.
`--cwd <path>`	Project directory.

Examples

Basic run

prompts-gpt run -f .prompts-gpt/code-review.md

Specify provider and model

prompts-gpt run -f .prompts-gpt/refactor.md --agent codex --model gpt-5.5

Dry run (preview)

prompts-gpt run -f .prompts-gpt/refactor.md --dry-run

JSON output for scripting

prompts-gpt run -f .prompts-gpt/tests.md --json --non-interactive

Background Cursor agent

prompts-gpt run -f .prompts-gpt/fix-bugs.md --agent cursor --background

Interactive Mode

When run without -f in an interactive terminal, run presents:

A file picker to select the prompt
A provider picker (if multiple are available)
A model picker for the selected provider

Auto-Detection

If --prompt-file is omitted:

Looks for a defaultPromptFile in .prompts-gpt/config.json
If only one .md file exists in .prompts-gpt/, auto-selects it
Otherwise prompts interactively

Artifacts

Each run creates an artifact directory:

.scripts/runs/
  agent-YYYYMMDDHHMMSS-PID-HASH/
    raw-output.log       # Full agent stdout/stderr
    summary.md           # Extracted summary
    meta.json            # Run metadata (provider, model, duration, exit code)

Run Result

The RunPromptResult returned (and printed with --json) includes:

{
  ok: boolean;
  provider: string;
  model: string;
  exitCode: number;
  durationMs: number;
  outputFile: string;
  summaryFile: string;
  tokenUsage: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
  };
  error?: string;
}

Provider-Specific Behavior

Codex

Uses --full-auto mode by default
Sandbox: workspace-write (configurable via --sandbox)
Requires OPENAI_API_KEY or ChatGPT login

Claude Code

Uses --dangerously-skip-permissions with --permission-mode acceptEdits
Prints output with --output-format stream-json

Cursor

Uses cursor --prompt with the prompt content
Supports --background for cloud agent mode
MCP auto-approval enabled by default (disable with --no-approve-mcps)

Copilot

Uses gh copilot with appropriate subcommand