> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Local CLI Changes

> How to test unreleased CLI changes outside the monorepo using your local build.

When you modify the CLI or any package it bundles (core, engine, producer, studio), you need to test those changes against real projects *outside* the monorepo — the same way an end user would run `hyperframes preview`.

## Prerequisites

Build the monorepo first. Every time you change source files, rebuild before testing.

```bash theme={null}
# From the monorepo root
bun run build
```

## Option 1: bun link (recommended)

`bun link` makes the `hyperframes` binary in your `$PATH` point at your local build. It survives across terminal sessions and auto-picks up new builds without re-linking.

```bash theme={null}
# If you previously installed hyperframes globally, remove it first —
# a global install takes priority over bun link and shadows your local build.
npm uninstall -g hyperframes 2>/dev/null

# Link your local build
cd packages/cli
bun link

# Verify — should print your local version AND point to the monorepo
hyperframes --version
which hyperframes
```

Now use `hyperframes` normally in any directory:

```bash theme={null}
cd ~/my-video-project
hyperframes preview .
```

**After every `bun run build`** the linked binary is already up to date — no re-linking needed.

To restore the published release when you're done:

```bash theme={null}
bun unlink hyperframes
npm install -g hyperframes@latest
```

## Option 2: node alias (no PATH changes)

If you don't want to touch your global `$PATH`, add a shell alias or call `node` directly:

```bash theme={null}
# Temporary alias for your current shell session
alias hyperframes="node /path/to/hyperframes/packages/cli/dist/cli.js"

# Or invoke directly
node /path/to/hyperframes/packages/cli/dist/cli.js preview .
```

Replace `/path/to/hyperframes` with your actual monorepo path.

## Option 3: npm pack (test the exact published artifact)

Use this when you want to verify what would actually ship in a release, including the bundled studio and examples.

```bash theme={null}
cd packages/cli
npm pack
# Creates: hyperframes-<version>.tgz

# Test it in an isolated directory
mkdir /tmp/pack-test && cd /tmp/pack-test
npx /path/to/hyperframes/packages/cli/hyperframes-<version>.tgz init my-video
cd my-video
npx /path/to/hyperframes/packages/cli/hyperframes-<version>.tgz preview .
```

## Testing the fix branches

When validating a specific bug fix, extract one of the test project archives and run through the scenario:

```bash theme={null}
# Example: testing audio-after-seek fix
unzip golden-lyric-video.zip && cd golden-lyric-video
hyperframes preview .
# 1. Press Play — confirm audio plays
# 2. Drag the timeline scrubber to a different position
# 3. Press Play again — audio should resume from the seeked position
```

Common test scenarios:

| Bug                        | Project                    | Steps                                             |
| -------------------------- | -------------------------- | ------------------------------------------------- |
| Audio silent after seek    | `golden-lyric-video`       | Play → seek → play again, verify audio            |
| Render stuck at 0%         | any                        | Renders tab → Export → watch progress bar         |
| Download 404 after restart | any                        | Complete a render → `Ctrl+C` → restart → Download |
| Timeline stops early       | `intro-vid`                | Play → should reach `0:05`, not stop at `0:03`    |
| Lottie missing             | `hyperframe-build-up-demo` | Play → rocket visible during 0–2 s                |
| Blank thumbnails           | any                        | Compositions sidebar should show previews         |

## Troubleshooting

**Changes not reflected after `bun run build`**

The CLI binary is a single bundled file at `packages/cli/dist/cli.js`. If your change is in `@hyperframes/core` or another workspace package, make sure `bun run build` rebuilt *all* packages — the CLI bundles its dependencies at build time.

**`hyperframes` still shows the old version / old UI**

A globally installed `hyperframes` package shadows `bun link`. Check which binary is active:

```bash theme={null}
which hyperframes
```

If it points to a global store rather than your monorepo, remove the global install and re-link:

```bash theme={null}
npm uninstall -g hyperframes
cd packages/cli && bun link
```

**Port already in use**

`hyperframes preview` defaults to port 3002 and auto-increments if it's taken. Pass `--port` to use a specific port:

```bash theme={null}
hyperframes preview . --port 4000
```