Test local CLI changes

Run an unreleased HyperFrames CLI build against a real project outside the monorepo.

Package tests do not prove that the CLI behaves correctly in an ordinary video project. After the focused tests pass, run the changed command against a project outside the HyperFrames repository.

Build the workspace

From the repository root:

bun install
bun run build

Rebuild after changing CLI code or a package bundled by the CLI.

Run the local build

Choose one method.

Link the CLI

Use this when you will test several commands or projects:

cd packages/cli
bun link

hyperframes --version
which hyperframes

The resolved binary should point into the local HyperFrames checkout. Run it from a separate project:

cd /path/to/a/video-project
hyperframes lint
hyperframes check
hyperframes preview

Remove the link when finished:

bun unlink hyperframes

Call the built entry directly

Use this when you do not want to change your PATH:

node /path/to/hyperframes/packages/cli/dist/cli.js preview /path/to/a/video-project

Test the package archive

Use this before a release to check the files that would actually be published:

cd packages/cli
npm pack
npx ./hyperframes-<version>.tgz --help

Run the archive against an isolated project as well as the command you changed.

What to verify

Test the user-visible outcome, not only the exit code:

• the command accepts the documented arguments;
• errors explain how to recover;
• --json remains machine-readable when the command supports it;
• Preview opens the correct project and reflects file changes;
• a render produces a playable file with the expected duration and media;
• temporary files and background processes are cleaned up after success and failure.

For Studio changes, exercise the exact interaction in Preview. For rendering changes, inspect the output with ffprobe or the repository’s existing fixture tests rather than relying on visual playback alone.

Common problems

If a globally installed CLI shadows the link, inspect which hyperframes, remove the global package, and link again. Preview starts at port 3002 and automatically tries a free port; pass --port only when a fixed port is required.