@docyrus/animaguru 0.10.0 → 0.13.0

package/README.md

@@ -222,6 +222,49 @@ animaguru assets submit PROJECT_ID --file speech.json --model gemini-3.8-flash-t
 
 `--model` overrides the file's model. Unrelated type-specific flags are rejected rather than ignored. Individual downloads and complete ZIP exports refuse to overwrite existing files. Generated files are saved in the project's `assets/<id>/` directory and are shared with the web Assets workspace.
 
+## HeyGen avatars
+
+CLI 0.13.0 adds `avatars` for HeyGen's avatar API. A group is a character; its looks are outfits, poses or styles, and a look ID is what HeyGen renders with. Any project can browse HeyGen's public catalog. An avatar you create belongs to the project that created it: only that project lists, changes or deletes it.
+
+```sh
+animaguru avatars list PROJECT_ID --limit 10
+animaguru avatars looks PROJECT_ID --avatar-type studio_avatar
+animaguru avatars list PROJECT_ID --ownership private
+
+# A synthetic character from a description.
+animaguru avatars create PROJECT_ID --type prompt --name "Ada" \
+  --prompt "Woman in her early 30s, warm smile, navy blazer, bright studio, soft key light" \
+  --aspect-ratio 16:9 --dry-run
+# A new outfit or setting for one of the project's avatars.
+animaguru avatars create PROJECT_ID --type prompt --name "Ada, keynote" \
+  --look LOOK_ID --prompt "On a conference stage under a spotlight" --yes
+# A photo avatar from a saved image, an HTTPS URL or a local file.
+animaguru avatars create PROJECT_ID --type photo --name "Sam" \
+  --file portrait.jpg --subject-consent --yes
+animaguru avatars wait PROJECT_ID LOOK_ID
+```
+
+`create` and `add-looks` return the new look IDs. Looks start `processing`; `avatars wait` polls until HeyGen finishes (`completed`) or fails. `--file` and `--reference-images` take a project image's SHA (from `assets list`, or a character's `art`), an HTTPS URL HeyGen downloads (up to 32 MB), or a local file sent inline (up to 8 MB). Photos and footage show a real person: pass `--subject-consent` only when that person agreed to become an avatar.
+
+A digital twin trains on footage of a real person (about two minutes of natural talking: a project video SHA, a URL or a local file) and clones their voice. It renders only after that person records consent on camera:
+
+```sh
+animaguru avatars create PROJECT_ID --type digital_twin --name "Sam" \
+  --file https://example.com/sam-footage.mp4 --subject-consent --yes
+animaguru avatars consent PROJECT_ID GROUP_ID      # a 24-hour link for that person
+animaguru avatars get PROJECT_ID --group GROUP_ID  # consentStatus: pending, accepted or rejected
+```
+
+Look Packs dress one of the project's looks in a themed set of five looks; a single template makes two. `avatars templates` lists their IDs, each in a female and a male variant:
+
+```sh
+animaguru avatars templates
+animaguru avatars add-looks PROJECT_ID --look LOOK_ID \
+  --template 5a8e6be843ee4321a014946bf62aa322 --aspect-ratio 9:16 --yes
+```
+
+Credits are charged once HeyGen accepts a request: 132 for a photo or prompt avatar, 213 for a digital twin, and 132 for each generated look (a Look Pack makes five). `--dry-run` validates and estimates offline; the server checks files, avatar ownership and credits before calling HeyGen. Paid requests carry a retry key, so a retried request is not charged twice. `avatars rename PROJECT_ID LOOK_ID --name NAME` and `avatars voice PROJECT_ID GROUP_ID --voice VOICE_ID` change the project's own avatars. `avatars delete PROJECT_ID --group GROUP_ID --yes` (or `--look LOOK_ID`) deletes for good; deleting an avatar's last look deletes the avatar. The server needs `AI_PROVIDER_KEY_HEYGEN`.
+
 ## Typed job files
 
 Use `animaguru jobs submit PROJECT_ID --file job.json --yes`. The server and CLI validate the same schema. Available job bodies:
@@ -334,6 +377,47 @@ Tokens, client configuration and resumable receipts stay under `~/.config/animag
 
 Only one YouTube command may run at a time. Normal cancellation releases its lock. After a forced process kill, check that no YouTube command is running before removing `youtube/operation.lock` in the configuration directory.
 
+## Cloud sync and versions
+
+CLI 0.11.0 adds `animaguru cloud` for Individual Pro and Team plans. It saves a video workspace, or a standalone video project, to AnimaGuru with every version. Use it to continue on another computer, work with your team and return to earlier versions. Personal cloud projects need your own Individual Pro or Team plan. A team's cloud projects need the team owner's Team plan, and every member can then save and download them.
+
+```sh
+animaguru auth login
+animaguru workspaces use TEAM_ID              # optional: create the cloud project in a team
+animaguru cloud link                         # creates a cloud project for this folder
+animaguru cloud push -m "First cut"          # saves a version
+animaguru cloud status                       # unsaved changes, and whether the cloud is newer
+animaguru cloud pull                         # brings in versions saved elsewhere
+animaguru cloud versions                     # newest first, with who saved each one
+animaguru cloud restore VERSION --path animations/intro/src
+animaguru cloud push                         # saves the restored files as the newest version
+animaguru cloud clone PROJECT_ID my-films    # another computer; run npm install afterwards
+animaguru cloud list
+```
+
+Run the commands anywhere inside the workspace; `--dir PATH` chooses another folder. What is not synced:
+
+- `node_modules/`, `dist/`, `production/exports/` and `production/frames/`;
+- `.env` files except `.env.example`, `.npmrc`, `*credentials*.json`, `*secrets*.json`, keys and logs;
+- anything matched by `.gitignore` or `.animaguruignore`;
+- symbolic links.
+
+Each version is a Git commit in the project's own Cloudflare Artifacts repository. Where a file is stored depends on its type, not its size:
+
+- **Media** (images except SVG, video, audio and ZIP bundles) is uploaded once by SHA-256 at any size, however many versions use it, and Git keeps a small pointer. Media counts toward the plan's media storage: 20 GB for Individual Pro and 100 GB for each team.
+- **Work files** (code, configs, briefs, JSON, SVG, fonts and everything else) are stored in Git at any size up to Artifacts' 32 MB per-file limit. A larger work file stops the push and is named; add it to `.animaguruignore` or move it.
+
+The sync store lives in `.animaguru/sync/`, separate from any Git repository you keep for the folder, and linking adds it to `.gitignore`. Git credentials are short-lived and repository-scoped.
+
+`push` refuses when the cloud has a newer version; `pull` brings it in first. Your other unsaved changes stay. When the same file changed on both sides, `pull` stops and lists it. Then:
+
+- `--prefer local` keeps yours, and the next push replaces the cloud copy;
+- `--prefer cloud` takes the cloud's, and keeps your copy in `.animaguru/sync/backups/`.
+
+`restore` makes the folder, or the `--path` files and folders, match an earlier version without rewriting history. Push afterwards to save the result as the newest version. Replacing unsaved changes requires `--yes` and keeps backups.
+
+Cloud files are never written into ignored or secret paths, through links, or outside the folder. If a plan ends, cloud projects stay readable: list, versions, pull, clone and download still work, but pushing waits until the plan is active again. `cloud unlink` stops syncing a folder without touching the cloud. `cloud delete PROJECT_ID --yes` deletes the project, all its versions and its stored files. The studio's Cloud page lists projects, versions and their files, with downloads.
+
 ## One brand, many animations
 
 ```sh