# CLI

> Install the voxal CLI and learn the commands for scaffolding, previewing, and shipping an app

`voxal` is the developer CLI for building and deploying voxal apps. It scaffolds projects,
runs them locally with live reload, bundles and validates them, and ships them to the
platform.

## Install

The CLI ships as the npm package `voxalsh` and requires Node.js 20 or newer.

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>

<Tab value="npm">

```bash
npm install -g voxalsh
```

</Tab>

<Tab value="pnpm">

```bash
pnpm add -g voxalsh
```

</Tab>

<Tab value="yarn">

```bash
yarn global add voxalsh
```

</Tab>

<Tab value="bun">

```bash
bun add -g voxalsh
```

</Tab>

</Tabs>

It installs two binaries, `voxal` and `voxalsh`, that run the same program. This
documentation uses `voxal` throughout. Run `voxal` with no arguments, or `voxal --help`, to
print usage at any time.

<Callout title="Fastest start">
You do not need a global install to begin. Run `npm create voxal-app <name>` to scaffold a
React starter that already lists `voxalsh` as a local dependency, so `npm run dev`,
`npm run build`, and `npm run deploy` work out of the box. See [voxal init](/cli/init) for
the difference between the two scaffolds.
</Callout>

## A typical session

```bash
voxal init myapp          # scaffold an app and link a project
cd myapp && npm install
voxal dev                 # iterate locally with live reload
voxal deploy              # ship it
ssh myapp@voxal.sh        # anyone can connect
```

## Commands

### Create and run

<Cards>
  <Card title="voxal init" href="/cli/init" description="Scaffold a new app and link it to a project." />
  <Card title="voxal dev" href="/cli/dev" description="Run the app locally in your terminal, reload on save." />
  <Card title="voxal build" href="/cli/build" description="Bundle and validate the app to disk, offline." />
</Cards>

### Ship

<Cards>
  <Card title="voxal deploy" href="/cli/deploy" description="Build and deploy the current app." />
</Cards>

### Account and projects

<Cards>
  <Card title="Authentication" href="/cli/auth" description="login, logout, and whoami." />
  <Card title="Projects" href="/cli/projects" description="List or delete your projects." />
  <Card title="Configuration" href="/cli/configuration" description="voxal.json and the files the CLI reads." />
</Cards>

## Command conventions

A few rules hold across every command.

- **Positional arguments** come without a dash. `voxal init myapp` and `voxal deploy ./dir`
  pass the name and directory positionally.
- **Flags** accept either `--key value` or `--key=value`. A value flag with no value is a
  usage error.
- **Most commands need no flags.** The everyday flags are documented on each command's page:
  [`--name`](/cli/deploy) for deploy, [`--out`](/cli/build) for build, and
  [`--no-browser`](/cli/auth) for login.

An unknown command exits with a non-zero status and points you at `voxal --help`.

---

Source: https://docs.voxal.sh/cli