alpic-ai__skybridge/docs/api-reference/cli.mdx

---
title: "CLI"
description: "Test, build, and run your app from the terminal"
icon: terminal
---

Skybridge ships one CLI, available as both `skybridge` and `sb` once it's installed in your project. 

It's a project dependency, not a global install, so run it through your package manager, or the [package scripts](#package-scripts) a scaffold sets up.

## `create`

Scaffold a new project. Run it before the package is installed with `npx`:

```bash
npx skybridge create
```

See [Quickstart](/get-started/quickstart) to scaffold and run a project.

## `dev`

Start the development server with hot module reloading and DevTools.

<CodeGroup>
```bash npm
npx skybridge dev
```
```bash pnpm
pnpm skybridge dev
```
```bash yarn
yarn skybridge dev
```
```bash bun
bun skybridge dev
```
```bash deno
deno run -A npm:skybridge/skybridge dev
```
</CodeGroup>

- Serves the MCP endpoint at `http://localhost:3000/mcp`
- Opens DevTools for local testing at `http://localhost:3000/`
- Watches files and restarts the server, with HMR for views

| Flag | Description |
|------|-------------|
| `-p, --port <number>` | Port to run on. Defaults to `3000`, or the next free port if it's taken. |
| `--tunnel` | Open an Alpic tunnel for remote testing and Playground access. |
| `--no-open` | Don't open DevTools when the server is ready. |
| `-v, --verbose` | Show tunnel logs. |
| `--plain` | Disable the interactive UI and stream the server's stdout verbatim, so you can pipe it through a formatter (e.g. `skybridge dev --plain \| bunyan`). |

The [scaffolded](/get-started/quickstart#scaffold-your-project) `package.json` adds a `dev:tunnel` script, shorthand for `skybridge dev --tunnel`.

The port also reads from the `PORT` environment variable. Set `SKYBRIDGE_OPEN=false` in your shell profile to skip opening DevTools on every run, the equivalent of always passing `--no-open`.

### Formatting structured logs

If your server uses a structured JSON logger like [bunyan](https://github.com/trentm/node-bunyan) or [pino](https://github.com/pinojs/pino), pass `--plain` and pipe through the logger's formatter:

```bash
skybridge dev --plain | bunyan
skybridge dev --plain | pino-pretty
```

## `build`

Compile your views and MCP server for production.

<CodeGroup>
```bash npm
npx skybridge build
```
```bash pnpm
pnpm skybridge build
```
```bash yarn
yarn skybridge build
```
```bash bun
bun skybridge build
```
```bash deno
deno run -A npm:skybridge/skybridge build
```
</CodeGroup>

The output lands in `dist/`, ready for the `deploy` script or `skybridge start`.

### Excluding packages from the server bundle

The build's last step bundles your server into a single deployable function with esbuild. Bundling means every reachable dependency has to be resolved, including ones your code never runs.

Some packages break that step. A common case is a logger with an optional native dependency, like [bunyan](https://github.com/trentm/node-bunyan), which does `require('dtrace-provider')` inside a `try/catch`. You never use DTrace, but esbuild still tries to resolve it and fails on the native binding.

List those packages in the Vite plugin's `serverExternal` to leave them out of the bundle:

```ts vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { skybridge } from "@skybridge/vite-plugin";

export default defineConfig({
  plugins: [react(), skybridge({ serverExternal: ["dtrace-provider"] })],
});
```

An external package stays a plain `import` in the output, resolved from `node_modules` at runtime. Only list packages your server doesn't need at runtime, or that your deployment target installs itself.

## `start`

Run the production server from the build output. Run `skybridge build` first.

<CodeGroup>
```bash npm
npx skybridge start
```
```bash pnpm
pnpm skybridge start
```
```bash yarn
yarn skybridge start
```
```bash bun
bun skybridge start
```
```bash deno
deno run -A npm:skybridge/skybridge start
```
</CodeGroup>

- Serves the MCP endpoint at `http://localhost:3000/mcp`
- Runs the compiled server and pre-built view assets from `dist/`

| Flag | Description |
|------|-------------|
| `-p, --port <number>` | Port to run on. Defaults to `3000`, or the next free port if it's taken. Also reads `PORT`. |

## `telemetry`

The CLI reports anonymous usage, on by default. Toggle it with `skybridge telemetry disable`, `enable`, or `status`. See [Telemetry](/resources/telemetry) for what's collected and every way to opt out.

## Package scripts

A scaffolded project wires the commands into `package.json`:

| Script | Command | Description |
|--------|---------|-------------|
| `dev` | `skybridge dev` | Start the development server. |
| `dev:tunnel` | `skybridge dev --tunnel` | Start the dev server behind an Alpic tunnel. |
| `build` | `skybridge build` | Build for production. |
| `start` | `skybridge start` | Serve the production build. |
| `deploy` | `alpic deploy` | Deploy through the Alpic CLI. See [Deploy](/ship/deploy) for per-platform setup. |

Run them with your package manager:

<CodeGroup>
```bash npm
npm run dev
npm run build
npm start
```
```bash pnpm
pnpm dev
pnpm build
pnpm start
```
```bash yarn
yarn dev
yarn build
yarn start
```
```bash bun
bun dev
bun build
bun start
```
```bash deno
deno task dev
deno task build
deno task start
```
</CodeGroup>

<CardGroup cols={3}>
  <Card title="Quickstart" icon="zap" href="/get-started/quickstart">
    Scaffold and run your first app
  </Card>
  <Card title="Ship" icon="cloud-upload" href="/ship">
    Deploy to your platform of choice
  </Card>
  <Card title="McpServer" icon="server" href="/api-reference/mcp-server">
    The server the CLI builds and runs
  </Card>
</CardGroup>