Prompt DrivenSTUDIO

CLI contract

CLI install

The PDS CLI is the preferred automation surface for agents and CI. It calls the public agent API and keeps output contracts stable for scripts.

Install and verify

Node.js 20 or newer is required. Install the public npm package and verify the binary before using it in automation.

npm install -g @promptdriven/pds
pds --version
pds --api-url https://video.promptdriven.ai auth status --json

Documented global flags

  • --api-url
  • --token
  • --profile
  • --project
  • --timeout
  • --json
  • --jsonl
  • --no-color
  • --verbose
  • --version

The parser accepts additional internal flags. Public docs do not advertise help output until it is implemented as a supported command.

Command paths

  • auth login
  • auth status
  • auth logout
  • auth token create
  • auth token list
  • auth token revoke
  • projects create
  • project get
  • project reset-pipeline
  • script get
  • script set
  • artifacts list
  • pipeline plan
  • pipeline run
  • pipeline status
  • jobs watch
  • jobs cancel
  • distribution generate
  • distribution status
  • distribution publish
  • distribution thumbnails upload
  • distribution connections list
  • distribution connection select
  • reference-library list
  • reference-library create
  • reference-library items list
  • reference-library policy get
  • reference-library policy set
  • reference-library bindings list
  • reference-library bindings attach
  • reference-library bindings update
  • reference-library bindings detach
  • reference-library grants list
  • reference-library grants add
  • reference-library grants revoke
  • release-video create
  • release-video preflight
  • release-video status

pipeline status behavior

status output uses the 15-stage agent view, not the 13-stage human UI list. The order is:

  1. 01setup
  2. 02script
  3. 03references
  4. 04tts-script
  5. 05tts-render
  6. 06audio-sync
  7. 07specs
  8. 08veo
  9. 09compositions
  10. 10music
  11. 11render
  12. 12stitch
  13. 13audit
  14. 14distribution-package
  15. 15distribution-publish
  • The human UI combines render and stitch under Render.
  • The human UI combines distribution-package and distribution-publish under Distribution.
  • The agent status API keeps those stages separate so automation can distinguish packaging, upload, render, and stitch failures.

Automation should branch on the explicit stage ids in setup, script, references, tts-script, tts-render, audio-sync, specs, veo, compositions, music, render, stitch, audit, distribution-package, distribution-publish.

Distribution connections

  • Use pds distribution connections list --json to list server-side platform connections.
  • Use pds distribution connection select --json to select the connection publish should use.
  • Publish uses a selected server-side platform connection; agents must not handle YouTube OAuth secrets.

Output contract

  • --json emits one final JSON object.
  • --jsonl emits one event object per line for streaming commands.
  • Commands that return a normal non-events result may end with a { "type": "result", "result": ... } wrapper.
  • jobs watch --jsonl may emit only streamed events and no separate terminal result wrapper.
  • The --jsonl error path emits a { "type": "error", ... } object.
  • Human mode is not for agent parsing.

Retry behavior and stability

  • Retry failed release-video stages with pds pipeline run --stage <stage> only when the service permits that scoped retry.
  • Adding JSON fields is non-breaking.
  • Renaming or removing documented fields is breaking.
  • Agents branch on error.code, exit code, and typed result fields, not prose.