Skip to main content
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:
Rebuild after changing CLI code or a package bundled by the CLI.

Run the local build

Choose one method. Use this when you will test several commands or projects:
The resolved binary should point into the local HyperFrames checkout. Run it from a separate project:
Remove the link when finished. bun unlink takes no package name — it unregisters whichever directory you run it from, so go back to the CLI package in your HyperFrames checkout first (an absolute path, since you are now inside the video project):

Call the built entry directly

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

Test the package archive

Use this before a release to check the files that would actually be published:
Run the archive against an isolated project as well as the command you changed. A hyperframes preview started through npx keeps its server running when the npx process is stopped. Stop the server by the process listening on its port, or the next run talks to the old one:

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.