@prompt-mv/cli

Prompt Orchestra developer CLI.

30-Second Quickstart

# 1) Set env vars (example values)
export PROMPT_ORCHESTRA_BASE_URL="https://api.promptorchestra.com"
export PROMPT_ORCHESTRA_ORGANIZATION_ID="org_..."
export PROMPT_ORCHESTRA_AUTHORING_API_KEY="sk_live_..."
export PROMPT_ORCHESTRA_ACCESS_TOKEN="eyJ..."

# 2) Verify credentials + connectivity
npx @prompt-mv/cli verify --check-human

# 3) Validate and normalize a desired-state spec
npx @prompt-mv/cli plan --spec ./examples/builder.desired-state.v1.minimal.json

Install

npm i -g @prompt-mv/cli

or

npx @prompt-mv/cli --help

Auth Model

Prompt Orchestra CLI uses two bearer credential types:

• PROMPT_ORCHESTRA_AUTHORING_API_KEY for machine authoring/control-plane operations.
• PROMPT_ORCHESTRA_ACCESS_TOKEN for human-gated runtime/approval/publish operations.

Command credential requirements:

• Machine key required: verify, plan, diff, apply
• Human token required: inspect, approve, publish
• Proof assembly only (no network auth): bundle

Why this split:

• Authoring changes should run through scoped machine credentials.
• Inspection, approvals, and publish decisions are human-gated and auditable.

Required Environment

• PROMPT_ORCHESTRA_BASE_URL
• PROMPT_ORCHESTRA_ORGANIZATION_ID
• PROMPT_ORCHESTRA_AUTHORING_API_KEY
• PROMPT_ORCHESTRA_ACCESS_TOKEN

Spec File (--spec)

--spec points to a JSON desired-state document with:

• schemaVersion: "builder.desired-state.v1"
• publishIntent
• optional top-level prompts for reusable authored prompt objects
• tools, skills, agents, evaluations, endpoints arrays
• per-skill promptComposition for canonical authored prompt attachments
• optional per-skill inspectSamples fixtures for structured preview/run proof
• legacy skills[].layers is rejected; the CLI does not translate it silently

Default if omitted:

• ./desired-state/builder.desired-state.v1.json

Minimal example in this package:

• examples/builder.desired-state.v1.minimal.json
• examples/builder.desired-state.v1.prompt-composition.fixture.json
• examples/builder.desired-state.v1.legacy-layers.invalid.json

For structured skills, add:

{
  "inspectSamples": {
    "preview": { "query": "preview probe" },
    "run": { "query": "run probe" }
  }
}

inspectSamples are proof fixtures, not runtime defaults. They let prompt-mv inspect use realistic, authored inputs for skills that require domain-specific variables.

Prompt-composition example:

{
  "schemaVersion": "builder.desired-state.v1",
  "publishIntent": { "mode": "draft_only", "targetEnvironment": "dev" },
  "prompts": [
    {
      "promptKey": "system-be-brief",
      "name": "System: Be Brief",
      "defaultSection": "foundation",
      "content": "Answer briefly and directly.",
      "publish": true
    }
  ],
  "tools": [],
  "skills": [
    {
      "skillKey": "answer-briefly",
      "name": "Answer Briefly",
      "modelSelection": { "by": "modelKey", "modelKey": "gpt-4.1-mini" },
      "promptComposition": [
        {
          "promptKey": "system-be-brief",
          "attachmentMode": "floating_latest_published",
          "positionIndex": 0
        }
      ],
      "toolBindings": []
    }
  ],
  "agents": [],
  "evaluations": [],
  "endpoints": []
}

prompt-mv apply matches prompts by promptKey, creates missing prompts, creates a new prompt version only when content or guidanceNotes changes, publishes when publish: true, and then attaches prompts to skill versions with replacePrompts.

Commands

• prompt-mv verify [--json] [--check-human]
• prompt-mv plan --spec <path> [--json]
• prompt-mv diff --spec <path> [--require-clean] [--json]
• prompt-mv apply --spec <path> [--json]
• prompt-mv inspect --spec <path> [--mode preview|run|both] [--json]
• prompt-mv bundle --spec <path> [--proof-run-id <id>] [--brief <path>] [--json]
• prompt-mv approve --proof-run-id <id> --type plan|apply|publish [--status approved|rejected] [--notes "..."] [--json]
• prompt-mv publish --proof-run-id <id> [--json]

Typical Workflow

verify -> plan -> diff -> apply -> inspect -> bundle -> approve -> publish

npx @prompt-mv/cli verify --check-human
npx @prompt-mv/cli plan --spec ./examples/builder.desired-state.v1.minimal.json
npx @prompt-mv/cli diff --spec ./examples/builder.desired-state.v1.minimal.json
npx @prompt-mv/cli apply --spec ./examples/builder.desired-state.v1.minimal.json
npx @prompt-mv/cli inspect --spec ./examples/builder.desired-state.v1.minimal.json --mode both
npx @prompt-mv/cli bundle --spec ./examples/builder.desired-state.v1.minimal.json
npx @prompt-mv/cli approve --type plan --status approved
npx @prompt-mv/cli approve --type apply --status approved
npx @prompt-mv/cli approve --type publish --status approved
npx @prompt-mv/cli publish

High-Value Command Examples

verify

npx @prompt-mv/cli verify --check-human
npx @prompt-mv/cli verify --json

plan

npx @prompt-mv/cli plan --spec ./examples/builder.desired-state.v1.minimal.json
npx @prompt-mv/cli plan --spec ./examples/builder.desired-state.v1.minimal.json --json

diff

npx @prompt-mv/cli diff --spec ./examples/builder.desired-state.v1.minimal.json
npx @prompt-mv/cli diff --spec ./examples/builder.desired-state.v1.minimal.json --require-clean

apply

npx @prompt-mv/cli apply --spec ./examples/builder.desired-state.v1.minimal.json
npx @prompt-mv/cli apply --spec ./examples/builder.desired-state.v1.minimal.json --json

publish

npx @prompt-mv/cli publish --proof-run-id <proofRunId>
npx @prompt-mv/cli publish --proof-run-id <proofRunId> --json

Note: in CLI v1, publish records an approved publish decision after proof/approval checks. Publish route execution is intentionally deferred.

inspect

npx @prompt-mv/cli inspect --spec ./examples/builder.desired-state.v1.minimal.json --mode both
npx @prompt-mv/cli inspect --spec ./examples/builder.desired-state.v1.minimal.json --mode preview --json

Note: inspect uses explicit inspectSamples when provided. If no sample is authored, it falls back to a generic { "query": "..." } probe because prompt content is no longer inferred from desired-state layers.

Exit Codes

• 0 success
• 2 input/schema failure Usually: missing --spec, invalid JSON, invalid schemaVersion, unresolved model keys. Check: spec path, JSON validity, and required fields.
• 3 auth/credential-kind failure Usually: machine command run with only an access token, or human command run with only an API key. Check: required env vars and the auth model above.
• 4 clean-check failure Usually: diff --require-clean detected changes. Check: run diff without --require-clean and inspect operations.
• 5 proof/approval precondition failure Usually: missing inspection evidence, stale apply/current-state proof artifacts, missing approvals, or disallowed publish intent for apply. Check: rerun plan -> diff -> apply, then inspect/bundle, and inspect bundle failures.
• 6 unsupported/banned surface detected Usually: legacy route usage (for example /api/v1/run or /api/runs/:id) in the route ledger. Check: .prompt-orchestra/proof/gate3/route-use-ledger.json.
• 7 remote execution failure Usually: upstream API errors, 5xx/timeout, or failed service operations. Check: --json output, route ledger, API health/config, and credentials.

Compatibility

• Node: >=18
• Recommended invocation: npx @prompt-mv/cli ...
• Also supported: global install (npm i -g @prompt-mv/cli) then prompt-mv ...
• Version alignment:
  • @prompt-mv/[email protected] targets @prompt-mv/[email protected]
  • SDK/contracts compatibility is coordinated by minor line (@prompt-mv/[email protected] with @prompt-mv/[email protected])

Artifacts And Output

The CLI writes deterministic proof artifacts under your working directory:

• Gate 3 artifacts: .prompt-orchestra/proof/gate3/
  • verify.json
  • plan.json
  • plan.normalized-state.json
  • diff.json
  • apply.json
  • inspect.json
  • current-state.json
  • route-use-ledger.json
• Proof runs: .prompt-orchestra/proofs/<proofRunId>/
  • bundle.json
  • route-use-ledger.json
  • approvals/*.json
• Pointer to latest proof run:
  • .prompt-orchestra/proofs/latest-proof-run-id.txt

All commands support --json for machine-readable envelopes (schemaVersion: "builder.cli.output.v1").

inspect.json includes both successful evidence and per-skill failure entries when inspection is only partially successful.

Trust Proofs

For release confidence, run:

npm run proof:cli:fresh-machine

This generates proof/cli-fresh-machine-proof.json and proves tarball-based npx execution from an empty folder.

Cross-platform proof is enforced in CI via:

• .github/workflows/cli-fresh-machine-matrix.yml

The matrix runs on ubuntu-latest, macos-latest, and windows-latest.