# Prompt Driven Studio Full Agent Docs Public automation context for Prompt Driven Studio agents. Prefer the PDS CLI, use JSON or JSONL output, and keep tokens out of repo files. ## Agent & CLI Docs Start at https://video.promptdriven.ai/agents. Paste the handoff prompt into Codex, Claude Code, Cursor, CI jobs, or shell agents. The web AGENTS.md route is fetchable context and not automatic project discovery. 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. Canonical links: - llms.txt: https://video.promptdriven.ai/llms.txt - Short machine-readable entry point with required links. - llms-full.txt: https://video.promptdriven.ai/llms-full.txt - One-shot public context file for agents with a larger window. - AGENTS.md: https://video.promptdriven.ai/AGENTS.md - Fetchable web instructions. This is not automatic repo discovery. - CLI contract: https://video.promptdriven.ai/agents/cli - Install path, global flags, command paths, output modes, and status stages. - Agent API: https://video.promptdriven.ai/agents/api - Endpoint map, envelopes, status polling, and event stream behavior. - Security: https://video.promptdriven.ai/agents/security - Token handling, scopes, CI secrets, and platform connection boundaries. - Errors: https://video.promptdriven.ai/agents/errors - Exit codes, structured errors, and retry decisions. - Release video workflow: https://video.promptdriven.ai/agents/workflows/release-video - Automate a release video from script, release notes, and changelog files. - Pipeline workflow: https://video.promptdriven.ai/agents/workflows/pipeline - Automate setup, script updates, planning, runs, status, and artifacts. Rules: - 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 --json or pds jobs watch --run-id --jsonl. - Treat release-video idempotency keys as exact-payload retry keys; changed payloads require inspect/resume/cancel/new-attempt triage. CLI install: npm install -g @promptdriven/pds pds --version Auth status: pds --api-url https://video.promptdriven.ai auth status --json ## CLI install 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 Documented global flags: --api-url, --token, --profile, --project, --timeout, --json, --jsonl, --no-color, --verbose, --version 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 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 result wrapper. jobs watch --jsonl may emit streamed events without a separate terminal result wrapper. The --jsonl error path emits an error object. Human mode is not for agent parsing. Status: pipeline status uses the 15-stage agent view: setup, script, references, tts-script, tts-render, audio-sync, specs, veo, compositions, music, render, stitch, audit, distribution-package, distribution-publish. render and stitch are separate. distribution-package and distribution-publish are separate. Distribution connections: use distribution connections list and distribution connection select. Publish uses a selected server-side platform connection; agents must not handle YouTube OAuth secrets. Reference Library: use reference-library list and reference-library items list to inspect permitted libraries, reference-library create to create a user-scoped library, reference-library grants list/add/revoke to manage library-level user access, reference-library policy get/set to inspect or change project capture policy, reference-library bindings list to inspect project bindings, and reference-library bindings attach/update/detach to pin, update, or remove project materializations. Attach accepts --reference-id for Reference Catalog targets or --target-json for other project artifacts. Non-dry-run mutations require --idempotency-key. Stability: adding JSON fields is non-breaking. Renaming or removing documented fields is breaking. Agents should branch on error.code, exit code, and typed result fields, not prose. ## Agent API The CLI is the preferred automation surface. Use raw documented API endpoints only when the CLI cannot fit the caller. Endpoints: - GET /api/agent/version: API and client version compatibility. - GET /api/agent/auth/status: Authentication status for the current token or profile. - POST /api/agent/auth/device/start: Start device login for interactive CLI auth. - POST /api/agent/auth/device/complete: Complete device login after browser approval. - POST /api/agent/auth/tokens: Create a scoped token. rawToken is shown once. - GET /api/agent/auth/tokens: List token metadata available to the caller. - DELETE /api/agent/auth/tokens/[tokenId]: Revoke a token by id. - POST /api/agent/projects: Create a project for automation. - GET /api/agent/projects/[projectId]: Read project metadata. - GET /api/agent/projects/[projectId]/script: Read a project script file. - PUT /api/agent/projects/[projectId]/script: Write a project script file. - GET /api/agent/projects/[projectId]/artifacts: List public project artifacts for automation. - GET /api/agent/reference-libraries: List Reference Libraries visible to the current token or project. - GET /api/agent/reference-libraries/[libraryId]/items: List visible items for a Reference Library. - POST /api/agent/projects/[projectId]/reference-libraries: Create a user-scoped Reference Library owned by the current token principal. - GET /api/agent/projects/[projectId]/reference-libraries/[libraryId]/grants: List library-level user grants for a Reference Library. - POST /api/agent/projects/[projectId]/reference-libraries/[libraryId]/grants: Grant library-level can-use or admin access to another user. - DELETE /api/agent/projects/[projectId]/reference-libraries/[libraryId]/grants/[grantId]: Revoke a library-level user grant. - GET /api/agent/projects/[projectId]/reference-library-policy: Read project Reference Library capture policy. - PATCH /api/agent/projects/[projectId]/reference-library-policy: Set project Reference Library capture policy. - GET /api/agent/projects/[projectId]/reference-library-bindings: List project Reference Library bindings and rights state. - POST /api/agent/projects/[projectId]/reference-library-bindings: Attach a pinned Reference Library item version to a project artifact. - POST /api/agent/projects/[projectId]/reference-library-bindings/[bindingId]/update: Dry-run or accept a newer Reference Library binding version. - DELETE /api/agent/projects/[projectId]/reference-library-bindings/[bindingId]: Detach a project Reference Library binding while preserving local alternatives. - POST /api/agent/projects/[projectId]/references/capture: Capture a saved project reference into the private draft Reference Library. - POST /api/agent/projects/[projectId]/references/publish-captured: Publish an already captured private-draft project reference. - POST /api/agent/projects/[projectId]/reset-pipeline: Reset pipeline state for scoped retries. - POST /api/agent/pipeline/plan: Plan a pipeline run. - POST /api/agent/pipeline/run: Run pipeline stages or a permitted retry. - GET /api/agent/pipeline/status: Read 15-stage agent pipeline status. - GET /api/agent/jobs/[jobId]: Read durable job state. - POST /api/agent/jobs/[jobId]: Cancel a job. - GET /api/agent/jobs/[jobId]/events: Stream job events as newline-delimited JSON. - POST /api/agent/distribution/package: Generate or refresh a distribution package. - GET /api/agent/distribution/package: Read distribution package status. - POST /api/agent/distribution/thumbnails/upload: Upload and optionally replace a selected YouTube thumbnail. - POST /api/agent/distribution/publish: Publish through a selected server-side connection. - GET /api/agent/distribution/connections: List server-side distribution connections. - POST /api/agent/distribution/connection: Select a distribution connection for publish. - POST /api/agent/release-video: Create and optionally wait for an end-to-end release video run. - POST /api/agent/release-video/preflight: Validate release-video readiness without mutating projects or starting paid work. Responses use an envelope with ok, data, and error fields. Long-running jobs return durable ids and may provide an events URL for newline-delimited JSON progress. Agent pipeline status returns stageOrder and stages using the 15-stage agent order. The human UI combines render/stitch under Render and distribution-package/distribution-publish under Distribution. Selected Style Guide is a project source artifact consumed by references, specs, video generation, compositions, music, audit, and conditional TTS script behavior. Style Guide changes can stale those downstream stages through project freshness. Distribution is not a direct Style Guide consumer. openapi.json is planned for a later phase. ## Security Use PDS_TOKEN for CI and store it only in the CI secret store. rawToken is returned once when a token is created. Never commit tokens, credentials, .env files, or generated token output. YouTube OAuth credentials and connected-account secrets stay server-side. Agents list and select distribution connections through the CLI and never store platform credentials in CLI config, repo files, or CI. Least-privilege scopes: - project:create - project:read - project:write - pipeline:run - artifact:read - distribution:package - distribution:publish - token:manage Cloud wildcard project tokens require a Firebase admin custom claim on a direct interactive admin auth flow. PDS agent-token profiles cannot mint cloud wildcard tokens. Release automation should use project:create with a project-scoped CI token instead. Secret redaction should preserve public metadata while removing credentials, bearer values, refresh values, and generated token strings. ## Errors CLI exit codes: - 1 unexpected: Unexpected CLI or runtime error. - 2 usage: Local argument or validation error. - 10 auth: Authentication is missing, expired, or invalid. - 11 forbidden: The token lacks a required scope or project grant. - 12 notFound: A project, job, token, or artifact was not found. - 20 idempotencyConflict: The idempotency key is already attached to different input. - 21 apiVersionMismatch: The CLI and service API versions are incompatible. - 30 quota: Credit, quota, or account capacity is insufficient. - 40 provider: A generation or publishing provider failed. - 50 audit: A quality gate or audit check failed. - 51 distributionGate: Distribution package or publish prerequisites are not met. - 52 publishPolicy: Publish scope, platform, or privacy policy blocked the request. - 53 pipelineResetConflict: The pipeline could not be reset because state changed. - 60 cancelled: The job was cancelled. - 61 timeout: The command timed out. - 70 server: The service returned a server-side error. JSON error shape: { "ok": false, "error": { "code": "missing_required_option", "message": "Missing required option --scopes", "details": {} } } Retry timeout only when the command is idempotent or has an idempotency key. Do not retry usage without changing arguments. Do not retry forbidden without changing scopes. Reattach rather than restart when a runId is known. If idempotency_key_reused reports a different release-video payload, inspect the returned owner run and changed request fields before using a distinct new-attempt key. ## Release video workflow Required scopes: project:create, project:read, project:write, pipeline:run, artifact:read, distribution:package, distribution:publish. End-to-end command: 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 Dry run: pds release-video create \ --project-name release-v1.8.0 \ --script release_video_script.md \ --release-notes CHANGELOG.md \ --changelog CHANGELOG.full.md \ --target publish \ --platform youtube \ --privacy unlisted \ --dry-run \ --json Fixed-project recovery: when a pre-authorized selected project has no outputs/agent/release-video/metadata.json sidecar, first run preflight with --bootstrap-selected-project, --script, and a release identity (--release-tag or --git-sha). Missing-sidecar --bootstrap-selected-project requires server policy: either the exact project id is configured in PDS_RELEASE_VIDEO_BOOTSTRAP_PROJECT_IDS or trusted videoProjects/{projectId}.releaseVideo.bootstrapAllowed: true metadata exists. If preflight reports releaseMetadataSidecar.source as bootstrapped, run create with the same inputs plus --force-regenerate. Existing initialized projects report releaseMetadataSidecar.source as existing. Already initialized selected-project sidecars do not need this bootstrap gate. Fixed-project preflight: pds release-video preflight \ --project pdd-release-bootstrap \ --bootstrap-selected-project \ --script release_video_script.md \ --git-sha "$GITHUB_SHA" \ --release-tag v0.0.279 \ --target publish \ --platform youtube \ --privacy unlisted \ --json Fixed-project create: pds release-video create \ --project pdd-release-bootstrap \ --bootstrap-selected-project \ --script release_video_script.md \ --git-sha "$GITHUB_SHA" \ --release-tag v0.0.279 \ --target publish \ --platform youtube \ --privacy unlisted \ --force-regenerate \ --idempotency-key "release:v0.0.279:$GITHUB_SHA:fixed-project" \ --wait \ --json Distribution prerequisite: list available connections with pds distribution connections list --json and select the publishing connection with pds distribution connection select --json when needed. Do not manage OAuth credentials through the CLI. Status: preserve runId, failed stage, and error.code. Inspect durable status with pds release-video status --run-id --json and pds pipeline status --project --json. Retry a single failed stage with pipeline run --stage only when the service permits that scoped retry. Idempotency recovery: release-video keys are exact-payload retry keys. When idempotency_key_reused returns owner metadata, inspect that run and the changed request fields; start a distinct new-attempt key only after confirming the original attempt should not be resumed. ## Pipeline workflow Required scopes: project:create, project:read, project:write, pipeline:run, artifact:read. End-to-end commands: pds projects create --name automation-demo --idempotency-key automation-demo:create --json pds script set --project automation-demo --file main_script.md --idempotency-key automation-demo:script --json pds pipeline plan --project automation-demo --to audit --json pds pipeline run --project automation-demo --to audit --dry-run --wait --json pds pipeline run --project automation-demo --to audit --idempotency-key automation-demo:audit --wait --json pds artifacts list --project automation-demo --json Project source artifacts: source script is required. Reference Catalog and selected Style Guide may already exist on the project. Selected Style Guide is not a timing manifest and is not a Phase 1 agent API endpoint. Style Guide freshness can mark tts-script, references, specs, veo, compositions, music, and audit stale. Distribution becomes stale through downstream render, audit, and package fingerprints rather than direct Style Guide freshness. Status: use pipeline status --json. The 15-stage agent view is setup, script, references, tts-script, tts-render, audio-sync, specs, veo, compositions, music, render, stitch, audit, distribution-package, distribution-publish. Async steps stream or poll progress while synchronous runner steps return JSON and should be followed by status refresh.