{"id":48768444,"url":"https://github.com/heygen-com/heygen-cli","last_synced_at":"2026-06-10T22:00:59.816Z","repository":{"id":351012907,"uuid":"1196457246","full_name":"heygen-com/heygen-cli","owner":"heygen-com","description":"Create AI videos from the terminal. Official CLI for the HeyGen video generation API.","archived":false,"fork":false,"pushed_at":"2026-06-02T19:24:20.000Z","size":6446,"stargazers_count":63,"open_issues_count":2,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-02T21:23:11.861Z","etag":null,"topics":["agents","ai","api","avatar","cli","golang","heygen","text-to-speech","video","video-translation"],"latest_commit_sha":null,"homepage":"https://developers.heygen.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heygen-com.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-30T18:06:56.000Z","updated_at":"2026-06-02T19:23:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/heygen-com/heygen-cli","commit_stats":null,"previous_names":["heygen-com/heygen-cli"],"tags_count":72,"template":false,"template_full_name":null,"purl":"pkg:github/heygen-com/heygen-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fheygen-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fheygen-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fheygen-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fheygen-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heygen-com","download_url":"https://codeload.github.com/heygen-com/heygen-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fheygen-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34172196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","api","avatar","cli","golang","heygen","text-to-speech","video","video-translation"],"created_at":"2026-04-13T09:00:46.123Z","updated_at":"2026-06-10T22:00:59.811Z","avatar_url":"https://github.com/heygen-com.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HeyGen CLI\n\n[![CI](https://github.com/heygen-com/heygen-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/heygen-com/heygen-cli/actions/workflows/ci.yml)\n[![Go 1.25](https://img.shields.io/badge/Go-1.25-00ADD8?logo=go)](https://go.dev)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\n\n**Make AI videos from the command line.** Drive HeyGen with code, not clicks.\n\n![demo](docs/demo.gif)\n\nFull reference and examples: **[developers.heygen.com/cli](https://developers.heygen.com/cli)**.\n\n## Built for\n\n- **Coding agents** — Claude Code, Codex, and others\n- **CI/CD pipelines** — weekly recap videos, release-note vlogs\n- **Bulk operations** — translate 100 videos in one shell loop\n- **Custom integrations** — wrap it in your own tool\n\n## Agent skills\n\n[heygen-com/skills](https://github.com/heygen-com/skills) — one-line install for Claude Code, Codex, and other agents. Create your own avatar and generate a video in a single conversation.\n\n## Agent-first by design\n\n- **JSON on stdout, structured errors on stderr, stable exit codes.**\n- **Self-describing.** `--request-schema` and `--response-schema` return JSON Schema without auth or API calls.\n- **Non-interactive by default.** Set `HEYGEN_API_KEY` and nothing reads a TTY.\n\n## Install\n\n```bash\ncurl -fsSL https://static.heygen.ai/cli/install.sh | bash\n```\n\nSingle static binary, no runtime required. Installs to `~/.local/bin`.\n\n**Supported platforms:** macOS, Linux, and Windows (via WSL).\n\nYou only need a HeyGen API key — see [Authenticate](#authenticate) below.\n\n## Updates\n\n```bash\nheygen update            # install the latest version\n```\n\n## Authenticate\n\nChoose one of the three options below. The first two are agent- and CI-friendly; the third is for humans.\n\n**1. Environment variable** — agents, CI; ephemeral, no file on disk:\n\n```bash\nexport HEYGEN_API_KEY=your-key-here\n```\n\n**2. Pipe to `auth login`** — agents; persists to `~/.heygen/credentials`:\n\n```bash\necho \"$KEY\" | heygen auth login\n```\n\n**3. Interactive `auth login`** — humans; persists to `~/.heygen/credentials`:\n\n```bash\nheygen auth login\n```\n\nVerify any of the above with `heygen auth status`. Get a key at [app.heygen.com/settings/api](https://app.heygen.com/settings/api).\n\n## Quick start\n\n**1. Create a finished video from a prompt** (returns JSON including `video_id`):\n\n```bash\nheygen video-agent create --prompt \"30-second product demo\" --wait\n```\n\n**2. Get its metadata and share link:**\n\n```bash\nheygen video get \u003cvideo-id\u003e\n```\n\nReturns JSON with `video_url` (raw mp4), `video_page_url` (shareable UI link), `thumbnail_url`, and `duration`. Pipe to `jq` to extract what you need:\n\n```bash\nheygen video get \u003cvideo-id\u003e | jq -r '.data.video_page_url'\n# → https://app.heygen.com/videos/...\n```\n\n**3. Download the mp4:**\n\n```bash\nheygen video download \u003cvideo-id\u003e\n```\n\nAdd `--human` to any command for a readable layout. Set `HEYGEN_OUTPUT=human` to make it the default.\n\n## Commands\n\nMirrors the [HeyGen v3 API](https://developers.heygen.com). Pattern: `heygen \u003cnoun\u003e \u003cverb\u003e`.\n\n| Group | What it does |\n|-------|-------------|\n| `video-agent` | Create videos from text prompts using AI |\n| `video` | Create, list, get, delete, download videos |\n| `avatar` | List and manage avatars and looks |\n| `voice` | List voices, design voices, generate speech |\n| `audio` | Search the background-music catalog |\n| `video-translate` | Translate videos into other languages |\n| `lipsync` | Dub or replace audio on existing videos |\n| `webhook` | Manage webhook endpoints and events |\n| `asset` | Upload files for use in video creation |\n| `user` | Account info and billing |\n\nEvery command supports `--help`.\n\n## How it behaves\n\n| Aspect | Behavior |\n|--------|----------|\n| **stdout** | Always JSON. Even `video download` — binary writes to disk; stdout emits `{\"asset\", \"message\", \"path\"}` so you can chain on `.path`. |\n| **stderr** | Structured envelope on error: `{\"error\": {\"code\", \"message\", \"hint\"}}`. Stable `code` values for programmatic branching. |\n| **Exit codes** | `0` ok · `1` API or network · `2` usage · `3` auth · `4` timeout under `--wait` (stdout contains partial resource for resume) |\n| **Request bodies** | Flags for simple inputs; `-d` for nested JSON (inline, file path, or `-` for stdin). Flags override matching fields. |\n| **Async jobs** | `--wait` blocks with exponential backoff; `--timeout` sets max (default 20m). 429s and 5xx retry automatically. |\n\nExample error envelope:\n\n```json\n{\"error\": {\"code\": \"not_found\", \"message\": \"Video not found\", \"hint\": \"Check ID with: heygen video list\"}}\n```\n\n## Configuration\n\n| File | Purpose |\n|------|---------|\n| `~/.heygen/credentials` | API key |\n| `~/.heygen/config.toml` | Output format and other non-secret settings |\n\n`HEYGEN_API_KEY` and `HEYGEN_OUTPUT` env vars override the respective files.\n\n```bash\nheygen config list       # show all settings with sources\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\n[Apache License 2.0](./LICENSE)\n\n## Links\n\n- [CLI Documentation](https://developers.heygen.com/cli)\n- [API Documentation](https://developers.heygen.com)\n- [Releases](https://github.com/heygen-com/heygen-cli/releases)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheygen-com%2Fheygen-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheygen-com%2Fheygen-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheygen-com%2Fheygen-cli/lists"}