---
title: "CLI Reference - BYO SDK"
slug: "cli-reference-byo-sdk"
updated: 2026-10-05T15:16:21Z
published: 2026-10-05T15:16:21Z
canonical: "docs.unqork.io/cli-reference-byo-sdk"
---

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

# CLI Reference - BYO SDK

The BYO SDK provides CLI tools and npm scripts for the full development lifecycle:

- **`create`**: Scaffold new projects.
- **npm scripts**: Dev server, builds, and preview.
- **`byo`**: Type checking, code generation, and version bumping.

## Project Scaffolding

Scaffold a new BYO project from a template using the `create` command.

### Usage

```bash
# Interactive mode (prompts for options)
npx --package=./sdk.tgz create

# Non-interactive mode
npx --package=./sdk.tgz create <name> [options]
```

### Arguments

| Argument | Description |
| --- | --- |
| `&#x3C;name>` | Asset name (kebab-case). Becomes the directory name and `byo.name` in `package.json`. |

### Options

| Option | Description |
| --- | --- |
| `--framework &#x3C;type>` | Component framework: `vanilla`, `react`, `vue`, `angular`, or `lit`. |
| `--component-name &#x3C;name>` | PascalCase component class name. Derived from `&#x3C;name>` if omitted. |
| `--typescript`, `--ts` | Use TypeScript (generates `.ts`/`.tsx` files and `tsconfig.json`). |
| `--javascript`, `--js` | Use JavaScript. |
| `--css-option &#x3C;type>` | CSS framework: `postcss` (default) or `plain`. |
| `--dry-run` | Preview files without writing anything. |

### Examples

```bash
# Interactive — prompts for framework, language, CSS framework, etc.
npx --package=./sdk.tgz create

# Vanilla + TypeScript with PostCSS (default)
npx --package=./sdk.tgz create my-button --framework vanilla --ts

# React + TypeScript with PostCSS
npx --package=./sdk.tgz create my-component --framework react --ts --css-option postcss

# React + TypeScript with Plain CSS (no preprocessing)
npx --package=./sdk.tgz create my-component --framework react --ts --css-option plain

# React + JavaScript with custom component name
npx --package=./sdk.tgz create my-react-component --framework react --js --component-name MyReactComponent

# Preview without writing files
npx --package=./sdk.tgz create my-component --framework vue --ts --dry-run
```

### Output Structure

```text
<name>/
├── package.json          # includes "byo" metadata field
├── vite.config.ts        # Vite configuration with byoPlugin
├── postcss.config.js     # PostCSS configuration (if --css-option postcss)
├── tsconfig.json         # TypeScript configuration (if --ts)
├── manifest.json         # component/event descriptors
├── src/
│   ├── entry.ts          # bundle entry — exports all components
│   ├── <ComponentName>.ts
│   ├── <ComponentName>.css    # component styles
│   ├── <ComponentName>.test.ts
│   ├── <ComponentName>.mocks.ts
│   └── shared.css        # shared styles (if --css-option postcss)
└── .env.example          # environment variable template
```

### CSS Framework Options

The `--css-option` flag determines how styles are processed:

#### PostCSS (default)

- Supports modern CSS features like nesting, mixins, and custom properties.
- Compiles to standard CSS for broad browser support.
- Includes `postcss.config.js` and `shared.css` for reusable styles.
- Recommended for most projects.

#### Plain CSS

- No preprocessing or build-time transformations.
- Traditional CSS with no additional dependencies.
- Suitable for simple styling needs or minimal build complexity.
- Styles are imported as raw strings and injected into Shadow DOM.

For detailed styling guidance, see the [Styling Guide](/unqorkai/docs/styling-guide-byo).

## npm Scripts

Scaffolded projects include the following npm scripts for development and builds:

### `npm run dev`

Start the development server with hot module reload and the host simulation harness.

```bash
npm run dev
```

#### What it does

1. Starts the Vite dev server with hot module reload.
2. Serves the host simulation harness.
3. Opens the browser at `http://localhost:5173`.
4. Auto-reloads on file changes.

#### Dev Harness Features

- **Scenario drop-down**: Switch between mock scenarios defined in `*.mocks.ts`.
- **Props panel**: Shows current prop values.
- **Commands panel**: Dispatch command events with test payloads.
- **Callback log**: Logs all callback invocations with payloads.
- **Console integration**: Callback events also logged to browser console.

### `npm run build`

Build for development (no version bump).

```bash
npm run build
```

#### What it does

1. Bundles the source code with Vite.
2. Generates `dist/manifest.json`.
3. Creates `dist/&#x3C;assetName>.tar.gz`.
4. Does not bump the version.

#### When to use

- Testing the build locally.
- Verifying the bundle without changing the version.

### `npm run build:prod`

Build for production with automatic version bumping.

```bash
npm run build:prod
```

#### What it does

1. Bumps the patch version in `package.json`.
2. Bundles the source code with Vite.
3. Generates `dist/manifest.json`.
4. Creates `dist/&#x3C;assetName>.tar.gz`.

#### Output Structure

```text
dist/
├── <assetName>.js        # bundled component code
├── manifest.json         # platform manifest
└── <assetName>.tar.gz    # upload artifact
```

#### When to use

- Building for production upload.
- Ready to deploy a new version.

### `npm run preview`

Serve the production build in the dev harness.

```bash
npm run preview
```

#### What it does

1. Serves files from `dist/` without rebuilding.
2. Opens the dev harness at `http://localhost:4173`.
3. Loads the production bundle with mock scenarios.

#### Differences from `npm run dev`

- Serves the minified production bundle.
- Does not watch for file changes.

#### When to use

- Verifying the production bundle works correctly after building.
- Running a final check on file size, performance, and errors before uploading.

### `npm test`

Run unit tests.

```bash
npm test
```

Runs all `*.test.ts` files using Vitest.

### `npm run lint`

Lint source code.

```bash
npm run lint
```

Runs ESLint on `src/` directory.

### `npm run typecheck`

Type-check TypeScript code without emitting files.

```bash
npm run typecheck
```

#### What it does

- Runs `tsc --noEmit` to verify type correctness.
- Reports type errors without generating output files.
- Automatically runs before `build` and `build:prod`.

#### When to use

- Verifying types without building.
- Getting fast feedback during development.
- Running type validation in CI/CD.

**Note**: available in TypeScript projects scaffolded with `--ts`.

## Code Generation

Add a new component, event, or command to an existing project using the `byo generate` command.

### Usage

```bash
npx byo generate <type> <name> [options]
```

### Arguments

| Argument | Description |
| --- | --- |
| `&#x3C;type>` | `component`, `event`, or `command` |
| `&#x3C;name>` | PascalCase name (e.g., `DatePicker`, `ItemSelected`, `ResetCounter`) |

### Options

| Option | Description |
| --- | --- |
| `--dry-run` | Preview files without writing. |

### Generate Component

```bash
npx byo generate component DatePicker
```

The command creates the following:

- `src/DatePicker.ts` — file extension varies by framework.
- `src/DatePicker.test.ts`.
- `src/DatePicker.mocks.ts`.
- `src/entry.ts` — updated with the new export.

The file extension is inferred from the following:

- Project framework (`react` → `.tsx` or `.jsx`).
- Presence of `tsconfig.json` (TypeScript → `.ts` or `.tsx`).

### Generate Event

```bash
npx byo generate event ItemSelected
```

Appends a new event definition to `src/&#x3C;ComponentName>/&#x3C;ComponentName>.schema.ts`:

```typescript
import { z } from 'zod'

export const ItemSelectedEvent = z.object({
  // Define event payload shape
})

export type ItemSelectedEvent = z.infer<typeof ItemSelectedEvent>
```

### Generate Command

```bash
npx byo generate command Reset
```

Adds a command definition to `src/&#x3C;ComponentName>.schema.ts`:

```typescript
import { defineCommand } from '@unqork/byo-sdk/schema'

const resetSchema = z.object({
  silent: z.boolean().optional(),
})

export const resetDefinition = defineCommand({
  name: 'Reset',
  type: 'reset',
  description: 'Reset component to initial state',
  schema: resetSchema,
})
```

The command is automatically added to the component's `commands` array and exported from `entry.ts`.

#### What happens

- Platform triggers containing **BYOC Execute** outputs can dispatch the command.
- Command events are named by `type`, like `reset`.
- The component listens using `addEventListener('&#x3C;componentType>:reset', handler)` — commands are namespaced as `&#x3C;componentType>:&#x3C;commandType>`.

### Examples

```bash
# Generate a new component
npx byo generate component TaskCard

# Generate an event
npx byo generate event TaskCompleted

# Generate a command
npx byo generate command Reset

# Preview without writing
npx byo generate component Calendar --dry-run
```

## SDK Version

Display the installed SDK version using the `byo version` command.

### Usage

```bash
npx byo version
```

### Example

```bash
npx byo version
# Output: @unqork/byo-sdk v1.2.3
```

## Global Options

All `byo` commands support the following options:

| Option | Description |
| --- | --- |
| `--help`, `-h` | Show command help. |
| `--dry-run` | Preview without executing (where applicable). |

## Typical Workflows

### Development Workflow

```bash
# Scaffold project
npx --package=./sdk.tgz create my-component --framework react --ts
cd my-component
npm install

# Start dev server
npm run dev

# Edit files, see changes in browser

# Add more components
npx byo generate component SecondComponent

# Run tests
npm test
```

### Build and Deploy Workflow

```bash
# Build for production
npm run build:prod

# Preview production bundle
npm run preview

# Upload dist/my-component.tar.gz to Unqork
```

## Troubleshooting

### Dev Server Won't Start

**Problem**: Dependencies not installed

**Solution**:

```bash
npm install
npm run dev
```

### Port Already in Use

**Problem**: `Error: listen EADDRINUSE: address already in use`

**Solution**: Vite will automatically try the next available port. Check the console output for the actual port being used.

### Build Fails with TypeScript Errors

**Problem**: `error TS2304: Cannot find name 'X'`

**Solution**:

1. Check that `tsconfig.json` includes your source directory.
2. Install missing type definitions: `npm install -D @types/X`.
3. Ensure imports are correct.

## Next Steps

- [Building Components](/unqorkai/docs/building-components-byo-sdk) — step-by-step guide.
- [Testing Guide](/unqorkai/docs/testing-guide-byo-sdk) — testing strategies.
- [SDK Overview](/unqorkai/docs/byo-sdk) — SDK features and configuration.

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-09-29 | Accuracy fixes: corrected byo CLI description (typecheck, not validation), removed undocumented BYO_* env var injection, corrected that npm run build also produces tar.gz (EN-8153). |
| 2026-05-01 | Initial publication |

JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser.

Cascading Style Sheets (CSS) is a style sheet language used for presenting how a HTML or XML document looks to end-users.

A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.

The Shadow DOM is a web standard that allows you to create encapsulated, hidden DOM subtrees for your web components. It provides a way to scope CSS styles and JavaScript behavior within a component, preventing them from leaking out and interfering with the rest of the page.

An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects.