Skip to content

docs: Add a reference page for the start command #598

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Zfinix merged 2 commits into from
Jun 17, 2026
+71 −1
Merged

docs: Add a reference page for the start command #598

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fea763b
docs: Add a reference page for the start command
Zfinix Jun 12, 2026
a2a0c9a
docs: Move start command into the reference section and link it from …
Zfinix Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/04-get-started/02-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ If you are using Cursor, you will need to **enable the MCP server** in your proj

## Start the server and the app

Start the server and the Flutter app by opening up a terminal window and running the `serverpod start` command:
Start the server and the Flutter app by opening up a terminal window and running the [`serverpod start`](../06-concepts/00-start-command.md) command:

```bash
$ serverpod start
Expand Down
70 changes: 70 additions & 0 deletions docs/06-concepts/00-start-command.md
View file
Open in desktop
Comment thread
Swiftaxe marked this conversation as resolved.
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
---
description: Reference for the serverpod start command, covering every option, the terminal UI shortcuts for migrations and hot restart, and the server arguments it forwards.
---

# Starting the server

The `serverpod start` command runs your project in development mode. It generates the latest code, starts the server with hot reload, and launches the companion Flutter app, all in a single interactive terminal.

```bash
serverpod start
```

Run it from anywhere inside your project folder.

When it boots the server, `serverpod start` applies any pending migrations. While it runs, you create and apply new migrations from the terminal UI (see [Terminal UI shortcuts](#terminal-ui-shortcuts)).

## Usage

```bash
serverpod start [options] [-- <server-args>]
```

## Options

| Option | Default | Description |
| --- | --- | --- |
| `-w`, `--watch` / `--no-watch` | `true` | Watch files and hot-reload using the Frontend Server for fast incremental compilation. Pass `--no-watch` to start the server with `dart run` instead. |
| `-d`, `--directory <path>` | auto-detect | Set the server package directory. Auto-detected from the current directory when omitted. |
| `--docker` / `--no-docker` | `false` | Start Docker Compose services if a `docker-compose.yaml` exists (typically Redis when running Postgres separately). Off by default; pass `--docker` to opt in. |
| `--tui` / `--no-tui` | `true` | Show the interactive terminal UI. Pass `--no-tui` to run without it, for example in scripts or non-interactive shells. |
| `--flutter` / `--no-flutter` | `true` | Launch the companion Flutter app alongside the server. Pass `--no-flutter` to start only the server. |
| `--flutter-device <name>` | `chrome` | Choose the device passed to `flutter run -d`. Use `web-server` for headless or CI runs. |
| `--flutter-option <arg>` | none | Forward an extra argument to [`flutter run`](https://docs.flutter.dev/reference/flutter-cli). Repeatable, e.g. `--flutter-option=--web-port=8090`. |
| `-h`, `--help` | | Print usage information. |

## Terminal UI shortcuts

The interactive terminal UI lists its shortcuts along the bottom. With the `serverpod start` terminal focused:

| Key | Action |
| --- | --- |
| **R** | Hot restart the server. |
| **M** | Create a migration from your current model changes (`Shift+M` to force). |
| **A** | Apply pending migrations to the database. |
| **P** | Create a repair migration to reconcile a drifted database (`Shift+P` to force). |

Saving a file hot-reloads the server automatically while watching is enabled.

## Passing arguments to the server

Arguments after `--` are forwarded to the running server. For example, to start it in a specific run mode:

```bash
serverpod start -- --mode staging
```

The server accepts the following arguments:
Comment thread
Swiftaxe marked this conversation as resolved.

| Argument | Allowed values | Default | Description |
| --- | --- | --- | --- |
| `-m`, `--mode` | `development`, `test`, `staging`, `production` | `development` | Set the run mode the server starts in. |
| `-r`, `--role` | `monolith`, `serverless`, `maintenance` | `monolith` | Set the role the server runs as. |
| `-l`, `--logging` | `normal`, `verbose` | `normal` | Set the logging level. |
| `-i`, `--server-id` | any | `default` | Set the id of this server instance. |
| `-a`, `--apply-migrations` | | `false` | Apply pending database migrations on boot. |
| `-A`, `--apply-repair-migration` | | `false` | Apply the repair migration on boot. |

:::note
`serverpod start` is intended for local development. For production, deploy the server instead. See [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md) or [Custom hosting](../08-deployments/custom-hosting/01-choosing-a-strategy.md).
:::
Loading