Prompt DrivenSTUDIO

Agent handoff

Agent & CLI Docs

Give automation one public handoff URL for Prompt Driven Studio. The CLI is the preferred surface; the pages and text routes here pin the public contract for agents, CI jobs, and shell scripts.

CLI installOpen llms.txt

CLI install

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

npm install -g @promptdriven/pds
pds --version

Then check auth against the public service before starting a workflow.

pds --api-url https://video.promptdriven.ai auth status --json

Handoff prompt

Handoff prompt

You are working with Prompt Driven Studio.

Start here:
https://video.promptdriven.ai/agents

Fetch https://video.promptdriven.ai/llms.txt before crawling. Use the PDS CLI
for automation. Prefer --json or --jsonl. Use --idempotency-key for
non-dry-run mutations. Never store tokens in repo files. Reattach to
long-running work with the returned runId.

Choose your agent

Codex: paste the handoff prompt into the Codex task or add equivalent repo-local AGENTS.md instructions. The web /AGENTS.md route is fetchable context, not automatic Codex discovery.

Claude Code: paste the handoff prompt or tell Claude to fetch /llms.txt, then use CLI examples with JSON output.

Cursor: paste the handoff prompt, point the agent at /agents and /llms.txt, and keep repo-local Cursor rules for local codebase conventions.

CI / GitHub Actions: use PDS_API_URL, PDS_TOKEN, --json, and --idempotency-key.

Generic shell agent: start with pds --version, pds auth status --json, then a workflow page.

Rules for agents

  • Always prefer --json for final output.
  • Use --jsonl for long-running jobs.
  • Never parse decorative or human output.
  • Never store tokens in repo files.
  • Always pass --idempotency-key for non-dry-run mutations.
  • Use --dry-run before release or publish actions.
  • Preserve runId, eventsUrl, process exit code, and error.code in summaries.
  • Reattach with pds release-video status --run-id <id> --json or pds jobs watch --run-id <id> --jsonl.
  • Treat release-video idempotency keys as exact-payload retry keys; changed payloads require inspect/resume/cancel/new-attempt triage.

Minimal release-video CI pattern

Keep tokens in the CI secret store, prefer JSON output, and include an idempotency key for non-dry-run mutations.

PDS_API_URL=https://video.promptdriven.ai \
PDS_TOKEN="$PDS_RELEASE_TOKEN" \
pds release-video create \
  --project-name release-v1.8.0 \
  --script release_video_script.md \
  --release-notes CHANGELOG.md \
  --changelog CHANGELOG.full.md \
  --repo-url https://github.com/promptdriven/studio \
  --repo-name promptdriven/studio \
  --git-sha "$GITHUB_SHA" \
  --release-tag v1.8.0 \
  --preset release-notes \
  --target publish \
  --platform youtube \
  --privacy unlisted \
  --idempotency-key "release:v1.8.0:$GITHUB_SHA" \
  --wait \
  --json

Verification checklist

  • CLI exit code is 0.
  • JSON or JSONL payload parses.
  • Returned ok, data, or a command-specific result field is present.
  • Long-running commands returned or resolved a runId.
  • Status or artifacts were verified with a follow-up command.

Current automation caveats

  • pipeline status exposes a 15-stage agent view that splits Render into render and stitch and Distribution into distribution-package and distribution-publish.
  • Selected Style Guide is a project source artifact. It can affect downstream freshness and generation behavior, but style-guide routes are not a Phase 1 agent API surface.
  • Some runner steps are synchronous and return JSON directly; agents should refresh status after those steps instead of assuming every stage has an event stream.

Start with the workflow pages for runnable sequences: release video and pipeline.