# CLI

Hypen command-line interface for creating and managing projects

# Hypen CLI

The Hypen CLI (`@hypen-space/cli`) is the recommended way to create, develop, and build Hypen applications.

## Installation

```bash
# Using Bun (recommended)
bun install -g @hypen-space/cli

# Using npm
npm install -g @hypen-space/cli
```

## Commands

### `hypen init`

Create a new Hypen project.

```bash
hypen init my-app
```

This creates a new directory with:
- Project structure with `src/components/` (or `src/modules/` for the server-based layout)
- TypeScript configuration
- A `hypen.json` configuration file
- Starter components (Router + Home + Counter) with state and actions
- Run scripts: `dev`, `studio`, `test`, `build`

### `hypen dev`

Start the development server with hot reload.

```bash
cd my-app
hypen dev
```

Options:
- `--port <number>`, `-p` - Port to run on (default: `3000`)
- `--debug`, `-d` - Enable debug mode
- `--a11y` - Print accessibility findings on every rebuild

One port serves every kind of client:

- **Web client** at `http://localhost:3000` — open it in a browser and your
  app is running. No setup, no separate client build.
- **Remote endpoint** at `ws://localhost:3000` — the same port speaks the
  Hypen remote protocol, so native runners, Studio, and Test Mode can all
  connect to it directly.

<img src="/tooling/web-client-home.png" alt="The built-in web client serving a freshly scaffolded app" />

The engine renders server-side and streams minimal patches to every
connected client. When you save a file, the CLI reloads all connected
clients: each one reconnects within about half a second and resumes its
session against the freshly loaded templates and module code. Primary
module state (like the current route) is preserved across reloads; nested
route-module state resets.

By default all connected clients mirror one scene — an action dispatched in
one browser tab (or on a connected device) is replayed to every other
client, which makes multi-device development seamless.

<img src="/tooling/web-client-counter.png" alt="The scaffold's counter screen in the web client" />

### `hypen build`

Build the application for production.

```bash
hypen build
```

Options:
- `--outDir <path>`, `-o` - Output directory (default: `dist`)
- `--minify`, `-m` - Minify the output
- `--sourcemap`, `-s` - Generate source maps

Outputs optimized assets ready for deployment.

### `hypen generate`

Generate component imports from the components directory.

```bash
hypen generate
```

Scans `src/components/` and produces a `components.generated.ts` file that wires up all discovered component templates and modules.

### `hypen run`

Install and launch your app on a native device or simulator.

```bash
hypen run android
hypen run ios
```

This command:
1. Starts a WebSocket dev server
2. Downloads the Hypen Runner app (cached in `~/.hypen/runners/`)
3. Lists connected devices/simulators and prompts you to pick one
4. Installs the runner app on the selected device
5. Launches it with a connection back to the dev server

The server stays running with hot reload until you press `Ctrl+C`.

**Platforms:**
- `android` — Requires `adb` (Android SDK platform-tools). Works with emulators and physical devices connected via USB.
- `ios` — Requires `xcrun` (Xcode command line tools). Runs on iOS Simulator. Boots the simulator automatically if needed.

Options:
- `--port <number>`, `-p` - Dev server port (default: `3000`)
- `--studio` - Open Hypen Studio alongside the device runner

The `--studio` flag launches the Studio IDE at the same time as the device runner, so you can edit components in the browser and see changes live on the device.

```bash
# Run on Android with Studio open
hypen run android --studio

# Run on iOS Simulator on a custom port
hypen run ios --port 8080
```

### `hypen studio`

Open [Hypen Studio](/docs/tooling/studio), a full in-browser IDE for developing and debugging Hypen apps. Includes a code editor with LSP support, live preview, file browser, state inspector, action log, time-travel debugging, and an integrated terminal.

```bash
hypen studio
```

<img src="/tooling/studio.png" alt="Hypen Studio with the live preview connected to a running app" />

For server-based projects, Studio starts your entry script for you (or
reuses an already-running dev server on the configured port) and connects
the preview to it — one command, no second terminal.

Options:
- `--port <number>`, `-p` - Port to run on (default: `5173`)
- `--open` - Open browser automatically (default: `true`)

Studio requires the Bun runtime. See the [Studio documentation](/docs/tooling/studio) for the full feature reference.

### `hypen test`

Open Studio directly in **Test Mode** — a multi-surface preview board with
live web cells (DOM and Canvas) plus Android and iOS device mirrors.

```bash
hypen test
```

<img src="/tooling/test-mode.png" alt="Test Mode with a live web cell rendering the app" />

Inside a project, `hypen test` boots (or reuses) the dev server itself and
opens with the previews already connected. Cells are fully interactive, and
actions are mirrored across every surface — tap a button in the web cell
and a connected device updates too. Outside a project it opens in
connect-only mode: paste any `ws://` dev-server URL to attach.

Options:
- `--port <number>`, `-p` - Dev server port (default: `3000`)
- `--open` - Open browser automatically (default: `true`)

### `hypen check`

Run the engine's accessibility conformance pass over your `.hypen` sources.

```bash
hypen check                                  # all project components
hypen check src/components/App.hypen         # specific files or dirs
```

Findings print per file. Suppress a finding with a trailing
`// hypen-a11y-ignore [rule-id]` comment, or project-wide via `hypen.json`:
`"a11y": { "ignoreRules": ["rule-id"] }`. Exit codes: `0` clean, `1`
findings, `2` couldn't check. Use `hypen dev --a11y` to get the same
findings on every rebuild during development.

## Project Structure

The CLI expects this structure:

```
my-app/
├── src/
│   └── components/
│       └── App/
│           ├── component.hypen    # UI template
│           └── component.ts       # Module logic
├── hypen.json
├── package.json
└── tsconfig.json
```

## Component Discovery

The CLI automatically discovers components by recursively scanning the `components` directory. Multiple naming conventions are supported (folder-based, index-based, sibling files, and single-file).

For the complete discovery reference, naming patterns, and nested component organization, see [Configuration](/docs/tooling/configuration).

## Configuration

Create a `hypen.json` in your project root:

```json
{
  "components": "./src/components",
  "entry": "App",
  "port": 3000,
  "outDir": "dist"
}
```

For a full reference of all configuration options, discovery patterns, and integration with existing backends, see [Configuration](/docs/tooling/configuration).

## Troubleshooting

### Port already in use

```bash
hypen dev --port 3001
```

### Clear cache

```bash
rm -rf node_modules/.hypen
hypen dev
```

## See Also

- [Hypen Studio](/docs/tooling/studio) — Full Studio IDE feature reference
- [Configuration](/docs/tooling/configuration) — Full config and discovery reference
- [Installation Guide](/docs/getting-started/installation)
- [Your First App](/docs/getting-started/first-app)
- [Language Server (LSP)](/docs/tooling/lsp)