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

# create-ship-app

> The Ship CLI: scaffold a new project, pick your shape, choose plugins and a deployment target — in one command.

`create-ship-app` is the Ship CLI. One command scaffolds a [pnpm](https://pnpm.io/) + [Turborepo](https://turbo.build/repo/docs) monorepo, copies your chosen plugins into the repo, and wires a deployment target — ready to run.

```bash theme={null}
npx @paralect/ship init
```

<Info>`npx create-ship-app@latest init` resolves to the same CLI. Both run version **3.0.0**.</Info>

It downloads the real template from [paralect/ship](https://github.com/paralect/ship), so what you scaffold is exactly what the docs describe — no abstraction layer between you and your code.

## The scaffold flow

`init` walks you through three questions, then builds the project.

<Steps>
  <Step title="Pick a setup">
    Two shapes — see [Architecture](/docs/architecture) for the full picture:

    * **PostgreSQL + TanStack Start** — full-stack. You get `apps/api` (Hono + oRPC + Drizzle + PostgreSQL) and `apps/web` (TanStack Start), with end-to-end types flowing from the API to the client.
    * **TanStack Start web-only** — `apps/web` only, no `apps/api`. Backend logic runs as type-safe [server functions](/docs/web/server-functions) inside the Start server. No database, no API to maintain.
  </Step>

  <Step title="Choose plugins">
    A multiselect — space to toggle, enter to confirm. Each plugin **merges into your codebase**, the same way `shadcn/ui` adds components. See [Plugins](/docs/plugins/overview).

    | Plugin          | What it adds                                                  |
    | --------------- | ------------------------------------------------------------- |
    | `auth-starter`  | better-auth wiring + the web sign-in/up pages and app shell   |
    | `admin`         | Admin dashboard with a user list (requires `auth-starter`)    |
    | `mailer`        | Resend + React Email templates → `@ship/emails`               |
    | `cloud-storage` | S3-compatible file upload (Garage in dev, Wasabi/AWS in prod) |
    | `notes`         | Notes CRUD — a worked example resource                        |
    | `ai-chat`       | Streaming AI chat via `@ship/ai` (requires `auth-starter`)    |

    `auth-starter` and `admin` are pre-selected for the full-stack setup. In the web-only setup, plugins that need a backend are hidden.
  </Step>

  <Step title="Choose a deployment target">
    Pick where this ships. The CLI drops the matching CI workflows and infrastructure-as-code into your repo.

    | Choice                           | Docs                                                                         |
    | -------------------------------- | ---------------------------------------------------------------------------- |
    | Digital Ocean Apps               | [/deployment/digital-ocean-apps](/docs/deployment/digital-ocean-apps)             |
    | Render                           | [/deployment/render](/docs/deployment/render)                                     |
    | Digital Ocean Managed Kubernetes | [/deployment/kubernetes/digital-ocean](/docs/deployment/kubernetes/digital-ocean) |
    | AWS EKS                          | [/deployment/kubernetes/aws](/docs/deployment/kubernetes/aws)                     |
  </Step>
</Steps>

A run looks like this:

```text theme={null}
Hey! Let's build your Ship 🚀

✔ What is the name of your project? … my-ship-app
? Which setup do you want? › - Use arrow-keys. Return to submit.
❯  PostgreSQL + TanStack Start (full-stack)
   TanStack Start web-only
? Which plugins do you want to install? (space to toggle, enter to confirm)
❯ ◉ auth-starter   better-auth wiring + web sign-in/up
  ◉ admin          Admin dashboard with a user list
  ◯ mailer         Resend + React Email templates
  ◯ cloud-storage  S3-compatible file upload
  ◯ notes          Notes CRUD — example resource
  ◯ ai-chat        Streaming AI chat via @ship/ai
? What deployment type would you like to use? › - Use arrow-keys. Return to submit.
❯  Digital Ocean Apps
   Render
   Digital Ocean Managed Kubernetes
   AWS EKS
```

Then start it:

```bash theme={null}
cd my-ship-app
pnpm start
```

`pnpm start` brings up infrastructure, runs migrations, and starts every service.

## Naming the project

Pass a directory to skip the name prompt:

```bash theme={null}
npx @paralect/ship my-ship-app
```

The CLI validates the name against npm rules and refuses to scaffold into a non-empty folder.

## Skipping the deployment prompt

Pass `--deployment` (`-d`) with a shortcut to answer that question up front:

```bash theme={null}
npx @paralect/ship my-ship-app --deployment do-apps
```

| Shortcut        | Target                           |
| --------------- | -------------------------------- |
| `do-apps`       | Digital Ocean Apps               |
| `render`        | Render                           |
| `do-kubernetes` | Digital Ocean Managed Kubernetes |
| `aws-eks`       | AWS EKS                          |

## Adding plugins later

The CLI doesn't stop at scaffold time. From inside an existing Ship project, pull a plugin into your repo:

```bash theme={null}
npx @paralect/ship install <plugin-name>
```

```bash theme={null}
npx @paralect/ship install ai-chat
```

`install` copies the plugin's resources, routes and packages into your codebase — `apps/api/src/resources/...`, `apps/web/src/routes/...`, `packages/...` — so from then on every line is yours to edit. See [Plugins](/docs/plugins/overview) for the full catalog.

## Command reference

| Command                   | Does                                    |
| ------------------------- | --------------------------------------- |
| `init`                    | Scaffold a new project interactively    |
| `<project-directory>`     | Scaffold into a named directory         |
| `install <plugin>`        | Merge a plugin into the current project |
| `-d, --deployment <type>` | Preselect the deployment target         |
| `-v, --version`           | Print the CLI version                   |