CLI install

Most GVS users do not need a CLI, API token, or AI agent. Open the Studio, sign in with the account that was approved, and start a project in the browser.

If /studio sends you to a pending or under-review status page at /welcome, your seat has not been activated yet. That is an account-approval state; contact support rather than debugging the CLI.

• The CLI host needs Node.js 20 or newer, npm access to install the package, and outbound HTTPS access to video.promptdriven.ai.
• The approving browser can be on a different machine. A headless or remote CLI host prints the verification URL; automatic browser opening is optional.
• The approving browser needs ordinary web access to the verification URL, the GVS auth callback, PDD Cloud and Firebase, and whichever Google or GitHub sign-in provider is configured. Allowlisting only video.promptdriven.ai is not sufficient for first-time browser authentication.
• GVS approval, project membership, scopes, credits, and provider capacity are separate from basic network reachability.

A cloud-sandboxed coding agent may report that a proxy is refusing connections to video.promptdriven.ai. That usually means the agent's egress policy does not allow the host; it is not, by itself, evidence of a GVS outage.

Check only basic reachability from the CLI host with:

curl -sS -o /dev/null -w "%{http_code}
" https://video.promptdriven.ai/

A 200 from / proves DNS, TLS, and HTTP reachability for that route only. It does not prove Studio auth, the agent API, project storage, billing, workers, or media providers. If the agent is blocked, use a normal terminal or allowlist the host and start a fresh sandbox session.

This walkthrough uses a dedicated, short-lived actor-scoped profile.--all-my-projects lets a newly approved user complete device login before a project exists; it does not select a project for later project-scoped commands.

npm install -g @promptdriven/pds

pds --api-url https://video.promptdriven.ai \
  --profile gvs-agent auth login --all-my-projects --expires-in 1d

pds --api-url https://video.promptdriven.ai \
  --profile gvs-agent auth status --json

pds --api-url https://video.promptdriven.ai \
  --profile gvs-agent projects create \
  --name gvs-first-project \
  --idempotency-key gvs-first-project:create --json

# Use the project id returned above for subsequent commands.
pds --api-url https://video.promptdriven.ai \
  --profile gvs-agent auth profile update \
  --project <project-id> --json

pds --api-url https://video.promptdriven.ai \
  --profile gvs-agent --project <project-id> \
  pipeline run --to audit --dry-run --json

For CI or a narrowly scoped operator, prefer a project-scoped token with only the scopes required by the workflow. Use --jsonor --jsonl and inspect structured error.code and details rather than matching prose.

• The default device-login scopes include project creation/read/write, pipeline execution, distribution publishing, and token management. Treat the profile as a privileged credential.
• Use a dedicated profile for an agent, keep actor-scoped access short-lived, and never put the raw bearer token in a repository, command argument, issue comment, or build log.
• The saved profile stores the local credential; logout removes the local copy but does not revoke the server token. Revoke or rotate the server token when it may be exposed.
• For CI, use a project-scoped least-privilege token such as project:read,pipeline:run,artifact:read where the workflow permits it.

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

• --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.

• auth login
• auth status
• auth logout
• auth profile update
• auth token create
• auth token list
• auth token revoke
• auth token rotate
• projects create
• project get
• project reset-pipeline
• script get
• script set
• script generate
• artifacts list
• artifacts delete
• pipeline plan
• pipeline run
• pipeline status
• pipeline stop
• storyboard approve
• jobs watch
• jobs cancel
• github-release-video create
• 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

status output uses the 16-stage agent view, not the 14-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. 08storyboard
9. 09veo
10. 10compositions
11. 11music
12. 12render-sections
13. 13stitch-full-video
14. 14audit
15. 15distribution-package
16. 16distribution-publish

• The human UI combines render-sections and stitch-full-video 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, section-render, and full-video stitch failures.

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

• 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.

• --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 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.

• "Proxy refusing connections" means the CLI host or sandbox likely lacks egress; test reachability from the same host and use a normal terminal or a fresh allowlisted session.
• auth_required means the profile has no usable credential or the session expired; complete device login and rerun auth status.
• forbidden can mean missing GVS approval, a missing token scope, or a missing project grant; inspect error.code/details and the token's project access.
• missing_project means the command needs --project or a saved profile project; --all-my-projects alone does not select one.
• quota can mean insufficient credits, account/provider capacity, or another service limit. Inspect structured error details; use the billing page for insufficient PDDC and support for account or provider capacity.
• A pending /welcome status means the seat is not active yet. It is not a CLI, DNS, or provider failure.
• A reachable browser Studio does not prove every agent API or pipeline operation is healthy; preserve server, auth, billing, worker, and provider failures as possible diagnoses.

For insufficient PDDC, open the billing page. For account approval or provider-capacity help, email support@promptdriven.ai.