Hs

hs · Huasheng CLI

From one sentence to a finished, publishable video

简体中文 · English

---

hs brings Huasheng's video creation pipeline to the command line. Give it a sentence or a script, and it handles storyboarding, narration, footage and composition — producing a video you can export or publish directly. You can step in and adjust at any point along the way.

A single self-contained binary. No Node, no Python, no runtime to install. Every command supports --json, designed for scripts and AI clients.

Step 1: install and sign in

Do this once, regardless of which client you use later.

Install

Pick whichever suits you — all three give you the same binary.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/superlcr/huasheng-cli/main/install.sh | sh

Windows, in PowerShell:

irm https://raw.githubusercontent.com/superlcr/huasheng-cli/main/install.ps1 | iex

Either installer downloads the package for your platform, verifies its SHA256, and extracts it to ~/.local/bin (%LOCALAPPDATA%\Programs\hs on Windows).

With npm, if you already live in the Node ecosystem or just want to try it first:

npx @superlcr/hs --help

npm install -g @superlcr/hs # the command is still hs

The npm package is a small launcher; the binary for your platform arrives as an optional dependency, so nothing is downloaded or compiled at install time.

Manual download instead of the installer

Grab the package for your platform from Releases, extract it, and place the executable anywhere on your PATH:

Every release ships a SHA256SUMS file. Verifying it is recommended:

shasum -a 256 -c SHA256SUMS

Both macOS packages are signed and notarized by Apple (Developer ID Application).

The Windows package is unsigned; SmartScreen may prompt on first run — choose

"More info → Run anyway".

Sign in

Open a new terminal, sign in, and confirm that hs can read your credit balance:

hs auth login

hs account

The CLI and every AI client share ~/.hs/credentials.json; you do not sign in separately.

No browser on that machine (SSH, a cloud server, a container)? Run hs auth login --no-browser, open the address it prints on any device, approve, and paste back the address the browser lands on (it starts with http://127.0.0.1 and will not load — that is expected).

Step 2: choose how you use it

Both paths use the same hs binary and the same sign-in — pick either, or both.

Option 1: use hs CLI directly

Use this path for exact commands, scripts, or batch jobs. hs make can start from one sentence or a complete script, run the creation workflow, wait for the finished video, and download it.

Create a video from one sentence:

hs make --script "Three little-known facts about West Lake" --out ./out.mp4

Request an MG-style video:

hs make --script "Explain Song dynasty tea whisking in 30 seconds" --mode mg --out ./tea.mp4

Read a long script from a file:

hs make --script @script.txt --out ./video.mp4

Or start from your own narration recording — a file on your computer or a public URL:

hs make --audio ./narration.m4a --out ./video.mp4

hs make --audio ./narration.m4a --transcript @words.txt --out ./video.mp4 # if you have the words

Huasheng keeps your voice and cuts footage to it. The transcript is optional; without it, Huasheng transcribes the recording. Supported formats are mp3, wav, flac, mp4 and m4a; hs uploads the file itself and you never need an internal storage address.

hs make approves the storyboard for you — that spends credits, and it prints how many. To read the storyboard and its price first, use the step-by-step commands instead. See the hs CLI guide for parameters, step-by-step editing, resuming, and exporting. See Scripting and automation for JSON, exit codes, and batches.

Option 2: use hs through MCP in an AI client

hs includes an MCP server. Any AI client that supports local STDIO MCP can launch it with:

{

"mcpServers": { "huasheng": { "command": "hs", "args": ["mcp", "serve"] } } }

This configuration simply tells the client to run hs mcp serve when Huasheng is needed. There is no separate hs MCP package to install, and you should not keep the command running yourself. If the client cannot find hs, replace command with the full path from which hs (where hs on Windows).

The following are setup examples for four common clients. For any other MCP client, enter the same command and args in its MCP server settings.

ChatGPT Desktop App

1. Open Settings → MCP servers → Add server
2. Enter huasheng and choose STDIO
3. Set Command to the full path to hs; add mcp and serve as the two arguments
4. Save and restart, then type /mcp and check that huasheng is connected

ChatGPT Desktop renders interactive timeline, preview, footage, and export cards. It shares ~/.codex/config.toml with Codex CLI, so this setup also enables hs there.

Claude Desktop App

1. Download [huasheng.mcpb](https://github.com/superlcr/huasheng-cli/releases/latest/download/huasheng.mcpb)
2. Double-click it, then select Install in Claude Desktop
3. Confirm the path to hs; the default is ~/.local/bin/hs

If you changed the install location, paste the full path from which hs (where hs on Windows). Continue if the first install warns that the extension is unsigned. Claude Desktop also renders interactive cards.

Codex CLI

codex mcp add huasheng -- hs mcp serve

codex mcp list

Do not add it again if you already configured huasheng in ChatGPT Desktop; both read ~/.codex/config.toml. See the OpenAI MCP documentation.

Claude Code CLI

claude mcp add --scope user huasheng -- hs mcp serve

claude mcp list

Both commands run in the same terminal where you just signed in, so plain hs resolves; if your shell cannot find it, substitute the full path from which hs (where hs on Windows). Codex CLI and Claude Code present complete text results instead of desktop interactive cards.

Use it through conversation

After setup, say in your AI client:

Make me a 30-second video about why the sky is blue

You can inspect and refine existing projects too:

List my recent Huasheng projects

Make the narration in clip 2 shorter

Replace clip 3 with more futuristic footage

Use my own file ./b-roll.mp4 for clip 2

Change the narrator to a warmer voice, and tell me the price first

Confirming a storyboard spends credits, and publishing makes the video public. hs marks those and the other one-way tools (deleting a project, footage or a preference, joining the priority lane) as destructive, so a client that confirms destructive tools asks you first; hs itself does not prompt. Changing the voice after production and adding footage to the library spend credits too; the MCP tools quote the price when asked.

More documentation

• hs CLI guide: step-by-step creation, states, and command groups
• Scripting and automation: JSON, exit codes, batch control, and IDs
• Sign-in, privacy, and requirements: credentials, network boundaries, platforms

Safety boundaries

• The CLI and every AI client share one local credential; hs never receives your Bilibili password.
• Approving a storyboard spends credits, and publishing goes public. So do changing the voice after production and adding footage to the library, and those credits are not refunded. hs does what the command says and reports the cost; whether you are asked first is up to you, your script, or your AI client.
• Scripts, narration recordings, and footage are uploaded to Huasheng for video creation; there is no separate telemetry channel or background updater. The only other connection is a once-a-day check of the latest release number on GitHub, which sends nothing but the hs version and can be turned off.

Upgrading

hs upgrade

For an installer build, this downloads the latest release, checks its SHA256, and swaps it in; for an npm install it runs npm i -g @superlcr/hs@latest. hs never downloads or replaces itself on its own. Once a day it asks for the latest release number and mentions it if yours is older; set HS_NO_UPDATE_CHECK=1 to turn that off.

AI clients that run hs mcp serve keep the old process until they restart. After upgrading, start a new session in Claude Code or Codex, or quit and reopen Claude Desktop; until then the client is still on the old version. Upgrading while a client is running is safe on every platform.

Feedback

Found a problem? Please open an issue and include the output of hs --version — it carries the commit and build time, which is the key to diagnosing anything.