> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
cd /path/to/a/video-project
hyperframes lint
hyperframes check
hyperframes preview
```

Remove the link when finished:

```bash theme={null}
bun unlink hyperframes
```

### Call the built entry directly

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

```bash theme={null}
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:

```bash theme={null}
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.