CLI#
@clipkit/cli is the command-line interface for Clipkit. Use it to scaffold projects, validate Sources, and (soon) preview + render locally.
Install#
npm install -g @clipkit/cli # or, no install: npx @clipkit/cli <command>
The CLI is published under Apache-2.0 and lives in the open at github.com/clipkit/clipkit-modern.
Commands#
clipkit init [name]#
Scaffold a new Clipkit project in a fresh directory.
clipkit init my-video cd my-video npm install
The scaffold writes:
| File | Purpose |
|---|---|
video.ts | A starter Source with one text element + one shape. Edit this. |
package.json | Pinned @clipkit/cli, @clipkit/protocol, @clipkit/runtime. |
tsconfig.json | Strict TS, moduleResolution: 'bundler'. |
AGENTS.md | Auto-loaded by AI agents working in this directory. |
README.md | One-page project notes. |
If you omit [name], the CLI scaffolds into the current working directory (only if it is empty).
clipkit validate <file>#
Schema-check a Source against the Clipkit Protocol.
clipkit validate video.ts # ✓ video.ts is a valid Clipkit Protocol v1.0 document. clipkit validate broken.json # ✗ broken.json failed validation (2 errors): # - elements.0.type: Invalid discriminator value # - width: Expected positive integer
Accepts .json, .ts, .tsx, .mts, .cts, .js, .mjs, .cjs. TypeScript files load via jiti — no separate build step.
Source resolution. The file must export the Source as one of:
defaultexport- A named export called
source,video,project, orcomposition - The only named export, if exactly one named export exists
If none of those match, the command errors with a list of the named exports it found.
Exit codes.
| Code | Meaning |
|---|---|
0 | Valid. |
1 | Validation errors. The list is printed to stderr; the parsed Source is not. |
2 | The file could not be loaded (syntax error, missing module, etc.). |
clipkit validate is the same function @clipkit/render-service runs before it spawns Chromium. If it passes here, the runtime will not reject the document for schema reasons.
clipkit preview <file> (coming soon)#
Open a local Vite-driven browser preview. Hot-reloads on save.
Today, this command validates the Source and opens the hosted playground at playground.clipkit.dev pre-loaded with your file. The local preview ships alongside the next render-service release.
clipkit render <file> -o <output.mp4> (coming soon)#
Render the Source to MP4 locally via @clipkit/render-service.
clipkit render video.ts -o out.mp4 --backend auto
Today, this command validates and prints the next steps for installing @clipkit/render-service directly. Direct CLI integration arrives with the next CLI release.
Global flags#
| Flag | Default | Description |
|---|---|---|
--version, -v | — | Print the CLI version. |
--help, -h | — | Show help for the current command. |
--cwd <path> | process.cwd() | Run as if invoked from <path>. |
License#
Apache-2.0. See packages/cli/LICENSE in the repo.