heygen-com--hyperframes/docs/contributing/testing-local-changes.mdx

---
title: Testing Local CLI Changes
description: 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
# 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
# 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
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
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
# 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
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
# 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
which hyperframes
```

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

```bash
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
hyperframes preview . --port 4000
```