# ClipDone Agents Guide

ClipDone is an AI video editing app for turning raw footage into finished short-form videos. Agents use the ClipDone CLI to create projects, upload media, generate edited videos, request revisions, edit subtitles, inspect status, and download exports.

## Install

Use the published CLI:

```bash
npm install -g @clipdone/cli
clipdone --help
```

For one-off use without a global install, use `npx @clipdone/cli` or `pnpm dlx @clipdone/cli`.

## Sign in

```bash
clipdone login
```

The login command opens a browser page where the user signs in and authorizes the CLI.
Use `clipdone login --no-open --print-auth-url` when the CLI should wait for a manual browser flow instead of trying to launch one itself.

The CLI returns structured JSON by default.

## Core workflow

```bash
clipdone me
clipdone projects
clipdone projects create
clipdone projects create --name "Project name"
clipdone projects <project_id> update --name "New title"
clipdone projects <project_id> upload ./IMG_825.mp4 --type footage
clipdone projects <project_id> upload ./music.mp3 --type music
clipdone projects <project_id> files
clipdone projects <project_id> process
clipdone projects <project_id> status
clipdone projects <project_id> outputs
clipdone projects <project_id> runs
clipdone outputs <output_id> download --out ./final.mp4
```

If a local path contains spaces or parentheses, quote it:

```bash
clipdone projects <project_id> upload "/path/with spaces/video (1).mp4" --type footage
```

## Revisions and subtitle edits

Request a new version from feedback:

```bash
clipdone projects <project_id> revise --feedback "Make the hook faster and remove the repeated sentence near the middle."
```

Request a new version from a feedback JSON file:

```bash
clipdone projects <project_id> revise --feedback-file ./feedback.json
```

Apply subtitle edits from JSON:

```bash
clipdone projects <project_id> revise --subtitles-file ./subtitles.json
```

`feedback.json` can be either:

```json
[
  { "content": "Cut the pause before the CTA.", "videoTimes": [{ "kind": "range", "start": 12.4, "end": 15.1 }] }
]
```

or:

```json
{ "feedbackNotes": [{ "content": "Make captions shorter in the intro." }] }
```

`subtitles.json` should be:

```json
{
  "subtitles": [
    { "id": "cue-id", "text": "Updated subtitle text", "start": 1.2, "end": 3.4 }
  ]
}
```

## Capabilities

- Create and list projects
- Create projects without a name and let ClipDone use the same default naming as the web app
- Upload footage, music, and scripts
- Start first-pass video generation
- Generate revised versions from feedback notes
- Apply subtitle text edits
- Poll project status with overall progress, current phase, and completion summary
- List project run history for first-pass generations and revisions
- Download rendered videos
- Prefer resource-oriented commands (`auth`, `projects`, `outputs`, `files`) with the resource ID immediately after the resource name when needed
- Revoke local agent access

## Security model

The user must authorize access in the browser. The CLI uses secure OAuth login, but account setup, billing, and legal
acceptance, and account profile changes remain user-controlled browser actions.

To revoke the current agent credential and remove local access:

```bash
clipdone revoke
```

Use `clipdone logout` only when you want to clear the local credential without contacting ClipDone.