Scene CLI

Scene CLI lets Codex, V, Makaron, or another agent work with video-first Scene projects: upload source video and supporting images, search both media types, turn a creative brief into a source-backed footage plan, download image originals, and materialize precise playable MP4 clips.

The public CLI connects to Scene by default. No local server is required for the hosted deployment.

Install

npm install --global [email protected]
scene --version
scene --help

Node.js 20 or newer is required. For a private or local Scene deployment, set DAM_API_URL. A personal account can provide SCENE_API_KEY; the existing DAM_API_TOKEN remains the unchanged legacy/admin override and takes priority. Never print or pass either credential in a command argument.

For a normal Makaron account, create a personal key from Scene's CLI dialog, then configure it once without placing it in shell history:

scene auth set-key
# paste the key at the hidden prompt
scene projects list --json

On macOS, Scene stores the personal key in Login Keychain. CI and secret managers can set SCENE_API_KEY instead. Once either is configured, no additional Scene login is required. Run scene auth remove-key to remove the locally saved copy, and revoke the key from Scene to stop it working on every device. scene login and scene logout remain compatibility aliases only.

export DAM_API_URL=http://127.0.0.1:8000
export DAM_API_TIMEOUT_SECONDS=120

Commands

# Discover projects and their indexing state
scene projects list
scene projects list --json

# Discover stable folder IDs inside a project
scene folders list --project PROJECT_ID
scene folders list --project PROJECT_ID --json

# Upload one file to the project root
scene upload ./video.mp4 --project PROJECT_ID --json

# Add a supporting image to the same video project
scene upload ./cover.HEIC --project PROJECT_ID --json

# Recursively upload a directory into a canonical Scene folder
scene upload ./shoot-day --project PROJECT_ID \
  --folder FOLDER_ID --jobs 8 --json

# Create a seven-day upload-only link bound to one project and folder
scene upload-grant create --name '客户补传' \
  --project PROJECT_ID --folder FOLDER_ID

# Optional expiry and quotas; the key/link appear only in create output
scene upload-grant create --name '临时员工上传' \
  --project PROJECT_ID --folder FOLDER_ID \
  --expires-in 12h --max-files 20 --max-bytes 10GiB --json

# Metadata contains no recoverable key
scene upload-grant list --json
scene upload-grant revoke GRANT_ID --json

# Global semantic search
scene search '两个小朋友一起玩' --limit 5 --json

# Search inside one project
scene search '羽毛球拍的完整生产过程' \
  --project PROJECT_ID --limit 10 --json

# Download returned images as originals and video ranges as playable MP4 files
scene search '仓库里的成品球拍' \
  --project PROJECT_ID \
  --export-dir ./scene-exports/warehouse \
  --json

# Plan footage for a creative brief
scene agent '找到羽毛球拍从原材料到成品，组织成 30–50 秒' \
  --project PROJECT_ID --json

# Plan and download selected video clips plus supporting image originals
scene agent '找到羽毛球拍从原材料到成品，组织成 30–50 秒' \
  --project PROJECT_ID \
  --export-dir ./scene-exports/racket-plan \
  --json

# Stream confirmed planning and search events
scene agent '找到羽毛球拍完整生产过程' --project PROJECT_ID --jsonl

# Generate multiple edit-equivalent sets from one retrieval pass
scene agent '做 5 套羽毛球拍生产过程，每套约 40 秒' \
  --project PROJECT_ID --json

# Equivalent explicit form for another Agent or CI workflow
scene agent '羽毛球拍生产过程，每套约 40 秒' \
  --project PROJECT_ID \
  --sets 5 \
  --export-dir ./scene-exports/racket-sets \
  --json

# Export an existing plan without rerunning the Agent or search
scene export ./scene-plan.json \
  --export-dir ./scene-exports/racket-plan \
  --profile social-1080p --jobs 4 --json

Use scene COMMAND --help for every option. --json returns one final document; --jsonl is the live Agent event stream and cannot be combined with --export-dir.

scene folders list reads the canonical folder tree. Use its stable folder.id for --folder; do not reconstruct folder identity from relative_path.

scene upload accepts MOV, MP4, M4V, WebM, JPEG, PNG, WebP, HEIC, and HEIF files, including directories. It hashes every source before creating an idempotent upload session, resumes from the server-confirmed byte offset, uses direct GCS resumable upload when available, and falls back to Scene API chunks. Progress stays on stderr while --json emits one final report with per-file upload_id, asset_id, and any retryable failures. If --folder is omitted, the CLI reads and sends the project's canonical root folder_id. Upload concurrency defaults to 8, matching the web uploader; use --jobs 1 through --jobs 8 only when the caller needs a lower bound.

scene upload-grant create is the only command that returns the capability key and distributable URL. Capture that output securely. Scene stores only an irreversible digest, so list and revoke cannot display the key again.

Retrieval and export contract

scene search --json, scene agent --json, and every exported manifest.json use one small public media contract:

{
  "clips": [
    {
      "source_url": "https://dam-video-search.vercel.app/v1/assets/.../media?...",
      "media_type": "video/mp4",
      "start": 12.3,
      "end": 17.8,
      "description": "What is visible and why this range is useful"
    }
  ]
}

Every item starts with source_url + media_type. For video, start and end are seconds in the original source. Images omit the range and refer to the whole source image. description folds the useful visual summary, editorial purpose, evidence, and boundary confidence into one human-readable string. Array order is edit order.

Provider implementation metadata is intentionally not part of the public manifest. Do not invent extra identity fields or parse identity from source_url. The URL is an opaque, stable, headerless Scene delivery capability that can be saved and passed directly to a browser or Remotion Lambda without a Scene credential.

Multi-set Agent output uses { "sets": [{ "title": "...", "clips": [...] }] }. Every item still has the same small public media contract, starting with source_url and media_type. Scene keeps internal identity and retrieval metadata while it allocates distinct source ranges, but does not leak those implementation details into the editing handoff. Exported bundles contain a root manifest.json, per-set manifests, and one shared assets/ directory.

--export-dir asks the Scene server to generate or reuse a derivative for each exact video range, downloads selected images as originals, and writes manifest.json. Images never call the video Clip API, and Scene does not cut videos during ordinary search.

The default social-1080p export keeps source aspect ratio, caps the long edge at 1920 without upscaling, uses browser-compatible H.264 High/yuv420p plus AAC audio, and is intended for TikTok-class editing and delivery. Use --profile preview-720p only for a smaller review proxy.

One export submits up to 20 ranges as one batch. Scene delegates the batch to its on-demand Cloud Run worker, which runs four bounded FFmpeg jobs by default and writes ready derivatives to GCS. Set --jobs 1 through --jobs 4 when the workload needs a different bound.

Agent skill

The npm package includes a self-contained Scene skill:

scene skill path
scene skill install --target ~/.agents/skills
scene skill install --target ~/.codex/skills
scene skill install --target ~/.openclaw/skills

The skill deliberately owns retrieval only. It keeps video as the primary editable timeline and treats images as supporting material. An editing agent can read manifest.json and pass the exported video clips and image originals to Makaron or another editor.

Error recovery

The CLI exits with code 0 on success and 1 on invalid input, API failure, or incomplete export. Errors go to stderr and include an agent-actionable next step:

| Error | Next action | | --- | --- | | API 401 / 403 | Configure scene auth set-key or SCENE_API_KEY; for legacy/admin access, check DAM_API_TOKEN without printing credentials. | | media media_capability_invalid | Reload the asset or rerun search once to obtain the current stable URL; if it still fails, treat the asset as revoked or unavailable. | | 404 project | Run scene projects list --json, choose an existing id, retry with --project. | | 409 / 422 | Inspect indexing state with scene projects list --json. | | 429 | Wait briefly, reduce parallel calls, retry once. | | 5xx | Verify service health with scene projects list --json, retry once. | | connection failure | Check DAM_API_URL, then run the project list command. | | timeout | Check project state; increase DAM_API_TIMEOUT_SECONDS if the API is healthy. | | media export failure | Keep the returned source reference and retry export once; do not claim a partial handoff succeeded. |

Development

cd packages/scene-cli
npm test
npm run pack:check