diff --git a/docs/06-concepts/cli/_category_.json b/docs/06-concepts/cli/_category_.json new file mode 100644 index 00000000..489f7fbd --- /dev/null +++ b/docs/06-concepts/cli/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "CLI", + "position": 23, + "collapsed": true, + "className": "sidebar-icon-tools" +} diff --git a/docs/06-concepts/cli/_generated/.markdownlint.yaml b/docs/06-concepts/cli/_generated/.markdownlint.yaml new file mode 100644 index 00000000..65b28da8 --- /dev/null +++ b/docs/06-concepts/cli/_generated/.markdownlint.yaml @@ -0,0 +1,8 @@ +MD001: false +MD013: false +MD014: false +MD024: false +MD041: false # MD041/first-line-heading/first-line-h1: First line in a file should be a top-level heading +# Temporarily disable MD012/no-multiple-blanks because the cli_tools adds +# an extra newline for commands without sub commands +MD012: false \ No newline at end of file diff --git a/docs/06-concepts/cli/_generated/cloud.md b/docs/06-concepts/cli/_generated/cloud.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/06-concepts/cli/_generated/completion.md b/docs/06-concepts/cli/_generated/completion.md new file mode 100644 index 00000000..a78d8f58 --- /dev/null +++ b/docs/06-concepts/cli/_generated/completion.md @@ -0,0 +1,52 @@ +## Usage + +```console +Command line completion commands + +Usage: serverpod completion [arguments] +-h, --help Print this usage information. + +Available subcommands: + generate Generate a command line completion specification + install Install a command line completion script + +Run "serverpod help" to see global options. +``` + +### Sub commands + +#### `generate` + +```console +Generate a command line completion specification + +Usage: serverpod completion generate [arguments] +-h, --help Print this usage information. +-t, --tool (mandatory) The completion tool to target + + [completely] Use the `completely` tool (https://github.com/bashly-framework/completely) + [carapace] Use the `carapace` tool (https://carapace.sh/) + +-e, --exec-name Override the name of the executable +-f, --file Write the specification to a file instead of stdout + +Run "serverpod help" to see global options. +``` + +#### `install` + +```console +Install a command line completion script + +Usage: serverpod completion install [arguments] +-h, --help Print this usage information. +-t, --tool (mandatory) The completion tool to target + + [completely] Use the `completely` tool (https://github.com/bashly-framework/completely) + [carapace] Use the `carapace` tool (https://carapace.sh/) + +-e, --exec-name Override the name of the executable +-d, --write-dir Override the directory to write the script to + +Run "serverpod help" to see global options. +``` diff --git a/docs/06-concepts/cli/_generated/create-migration.md b/docs/06-concepts/cli/_generated/create-migration.md new file mode 100644 index 00000000..f5e400d3 --- /dev/null +++ b/docs/06-concepts/cli/_generated/create-migration.md @@ -0,0 +1,14 @@ +## Usage + +```console +Creates a migration from the last migration to the current state of the database. + +Usage: serverpod create-migration [arguments] +-h, --help Print this usage information. + --empty Creates the migration even if there are no database changes. +-f, --force Creates the migration even if there are warnings or information that may be destroyed. +-t, --tag Add a tag to the revision to easier identify it. + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/create-repair-migration.md b/docs/06-concepts/cli/_generated/create-repair-migration.md new file mode 100644 index 00000000..bc614c5c --- /dev/null +++ b/docs/06-concepts/cli/_generated/create-repair-migration.md @@ -0,0 +1,16 @@ +## Usage + +```console +Repairs the database by comparing the target state to what is in the live database instead of comparing to the latest migration. + +Usage: serverpod create-repair-migration [arguments] +-h, --help Print this usage information. +-f, --force Creates the migration even if there are warnings or information that may be destroyed. +-t, --tag Add a tag to the revision to easier identify it. +-v, --version The target version for the repair. If not specified, the latest migration version will be repaired. +-m, --mode Used to specify which database configuration to use when fetching the live database definition. + [development (default), staging, production] + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/create.md b/docs/06-concepts/cli/_generated/create.md new file mode 100644 index 00000000..8b58b5a8 --- /dev/null +++ b/docs/06-concepts/cli/_generated/create.md @@ -0,0 +1,22 @@ +## Usage + +```console +Creates a new Serverpod project, specify project name (must be lowercase with no special characters). + +Usage: serverpod create [arguments] +-h, --help Print this usage information. +-f, --force Create the project even if there are issues that prevent it from running out of the box. +-n, --name (mandatory) The name of the project to create. + Can also be specified as the first argument. + +Project Template + --mini Shortcut for --template mini. +-t, --template Template to use when creating a new project + + [mini] Mini project with minimal features and no database + [server] (default) Server project with standard features including database + [module] Serverpod Module project + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/generate.md b/docs/06-concepts/cli/_generated/generate.md new file mode 100644 index 00000000..b8d7d0ce --- /dev/null +++ b/docs/06-concepts/cli/_generated/generate.md @@ -0,0 +1,15 @@ +## Usage + +```console +Generate code from yaml files for server and clients. + +Usage: serverpod generate [arguments] +-h, --help Print this usage information. +-w, --watch Watch for changes and continuously generate code. +-d, --directory The directory to generate code for (defaults to current directory). + (defaults to "") +-f, --force Regenerate even when the output looks up to date. Use this to rebuild after hand-editing or reverting generated files. + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/global_options.md b/docs/06-concepts/cli/_generated/global_options.md new file mode 100644 index 00000000..7c985b9d --- /dev/null +++ b/docs/06-concepts/cli/_generated/global_options.md @@ -0,0 +1,34 @@ +## Usage + +```console +Manage your serverpod app development + +Usage: serverpod [arguments] + +Global options: +-h, --help Print this usage information. +-q, --quiet Suppress all cli output. Is overridden by -v, --verbose. +-v, --verbose Prints additional information useful for development. Overrides --q, --quiet. +-a, --[no-]analytics Toggles if analytics data is sent. + (defaults to on) + --[no-]interactive Enable interactive prompts. Automatically disabled in CI environments. + --version Prints the active version of the Serverpod CLI. + --experimental-features Enable experimental features. Experimental features might be removed at any time. + +Available commands: + cloud Manage Serverpod Cloud projects through the Serverpod Cloud. + completion Command line completion commands + create Creates a new Serverpod project, specify project name (must be lowercase with no special characters). + create-migration Creates a migration from the last migration to the current state of the database. + create-repair-migration Repairs the database by comparing the target state to what is in the live database instead of comparing to the latest migration. + generate Generate code from yaml files for server and clients. + language-server Launches a serverpod language server communicating with JSON-RPC-2 intended to be used with a client integrated in an IDE. + mcp-server Start an MCP bridge to the `serverpod start` runner of one server project. + quickstart Creates a new Serverpod project with basic options. + run Run a script defined in the "serverpod/scripts" section of pubspec.yaml. + upgrade Upgrade Serverpod to the latest version. + version Prints the active version of the Serverpod CLI. + +Run "serverpod help " for more information about a command. +``` + diff --git a/docs/06-concepts/cli/_generated/language-server.md b/docs/06-concepts/cli/_generated/language-server.md new file mode 100644 index 00000000..2af433bb --- /dev/null +++ b/docs/06-concepts/cli/_generated/language-server.md @@ -0,0 +1,12 @@ +## Usage + +```console +Launches a serverpod language server communicating with JSON-RPC-2 intended to be used with a client integrated in an IDE. + +Usage: serverpod language-server [arguments] +-h, --help Print this usage information. + --[no-]stdio (defaults to on) + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/mcp-server.md b/docs/06-concepts/cli/_generated/mcp-server.md new file mode 100644 index 00000000..8cd87d0a --- /dev/null +++ b/docs/06-concepts/cli/_generated/mcp-server.md @@ -0,0 +1,12 @@ +## Usage + +```console +Start an MCP bridge to the `serverpod start` runner of one server project. + +Usage: serverpod mcp-server +-h, --help Print this usage information. +-s, --server-dir Path to the server project directory (the package that contains a `serverpod` dependency). Auto-detected from the current working directory if omitted. Pass this flag explicitly in monorepos with multiple server projects. + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/quickstart.md b/docs/06-concepts/cli/_generated/quickstart.md new file mode 100644 index 00000000..3eb35bef --- /dev/null +++ b/docs/06-concepts/cli/_generated/quickstart.md @@ -0,0 +1,21 @@ +## Usage + +```console +Creates a new Serverpod project with basic options. +Suitable for a simple project or quick experiment. +Specify project name (must be lowercase with no special characters). + +Usage: serverpod quickstart [arguments] +-h, --help Print this usage information. +-f, --force Create the project even if there are issues that prevent it from running out of the box. +-t, --template Template to use when creating a new project + + [server] (default) Server project with standard features including database + [module] Serverpod Module project + +-n, --name (mandatory) The name of the project to create. + Can also be specified as the first argument. + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/run.md b/docs/06-concepts/cli/_generated/run.md new file mode 100644 index 00000000..6d383431 --- /dev/null +++ b/docs/06-concepts/cli/_generated/run.md @@ -0,0 +1,13 @@ +## Usage + +```console +Run a script defined in the "serverpod/scripts" section of pubspec.yaml. + +Usage: serverpod run +-h, --help Print this usage information. + --script The name of the script to run. +-l, --[no-]list List all available scripts. + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/upgrade.md b/docs/06-concepts/cli/_generated/upgrade.md new file mode 100644 index 00000000..6b81d134 --- /dev/null +++ b/docs/06-concepts/cli/_generated/upgrade.md @@ -0,0 +1,11 @@ +## Usage + +```console +Upgrade Serverpod to the latest version. + +Usage: serverpod upgrade [arguments] +-h, --help Print this usage information. + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/_generated/version.md b/docs/06-concepts/cli/_generated/version.md new file mode 100644 index 00000000..b51295b7 --- /dev/null +++ b/docs/06-concepts/cli/_generated/version.md @@ -0,0 +1,11 @@ +## Usage + +```console +Prints the active version of the Serverpod CLI. + +Usage: serverpod version [arguments] +-h, --help Print this usage information. + +Run "serverpod help" to see global options. +``` + diff --git a/docs/06-concepts/cli/commands/_category_.json b/docs/06-concepts/cli/commands/_category_.json new file mode 100644 index 00000000..bf9b81ce --- /dev/null +++ b/docs/06-concepts/cli/commands/_category_.json @@ -0,0 +1,5 @@ +{ + "collapsed": false, + "label": "Commands", + "position": 4 +} diff --git a/docs/06-concepts/cli/commands/cloud/_category_.json b/docs/06-concepts/cli/commands/cloud/_category_.json new file mode 100644 index 00000000..ef0e971e --- /dev/null +++ b/docs/06-concepts/cli/commands/cloud/_category_.json @@ -0,0 +1 @@ +{"label": "cloud"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/cloud/_cloud.md b/docs/06-concepts/cli/commands/cloud/_cloud.md new file mode 100644 index 00000000..b0366f34 --- /dev/null +++ b/docs/06-concepts/cli/commands/cloud/_cloud.md @@ -0,0 +1,5 @@ +# serverpod cloud + +`serverpod cloud` forwards everything after it to the Serverpod Cloud CLI (`scloud`), so you can manage Serverpod Cloud projects without installing `scloud` separately. + +For the full set of Cloud commands and options, see the [Serverpod Cloud CLI reference](/cloud/reference/cli/introduction). diff --git a/docs/06-concepts/cli/commands/cloud/cloud.mdx b/docs/06-concepts/cli/commands/cloud/cloud.mdx new file mode 100644 index 00000000..fb1f2545 --- /dev/null +++ b/docs/06-concepts/cli/commands/cloud/cloud.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_cloud.md'; +import Cloud from '../../_generated/cloud.md'; + + + + diff --git a/docs/06-concepts/cli/commands/completion/_category_.json b/docs/06-concepts/cli/commands/completion/_category_.json new file mode 100644 index 00000000..580a7edd --- /dev/null +++ b/docs/06-concepts/cli/commands/completion/_category_.json @@ -0,0 +1 @@ +{"label": "completion"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/completion/_completion.md b/docs/06-concepts/cli/commands/completion/_completion.md new file mode 100644 index 00000000..aa87877e --- /dev/null +++ b/docs/06-concepts/cli/commands/completion/_completion.md @@ -0,0 +1,5 @@ +# serverpod completion + +`serverpod completion` sets up shell tab-completion for the `serverpod` command. Use the `install` subcommand to add completion to your shell, or `generate` to print a completion specification you can wire up yourself. + +Both subcommands target a completion tool with `--tool`, either [`completely`](https://github.com/bashly-framework/completely) or [`carapace`](https://carapace.sh/). For a walkthrough, see [Shell completion](/tools/shell-completion). diff --git a/docs/06-concepts/cli/commands/completion/completion.mdx b/docs/06-concepts/cli/commands/completion/completion.mdx new file mode 100644 index 00000000..cb5a705d --- /dev/null +++ b/docs/06-concepts/cli/commands/completion/completion.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_completion.md'; +import Completion from '../../_generated/completion.md'; + + + + diff --git a/docs/06-concepts/cli/commands/create-migration/_category_.json b/docs/06-concepts/cli/commands/create-migration/_category_.json new file mode 100644 index 00000000..a3a586b0 --- /dev/null +++ b/docs/06-concepts/cli/commands/create-migration/_category_.json @@ -0,0 +1 @@ +{"label": "create-migration"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/create-migration/_create-migration.md b/docs/06-concepts/cli/commands/create-migration/_create-migration.md new file mode 100644 index 00000000..367048ec --- /dev/null +++ b/docs/06-concepts/cli/commands/create-migration/_create-migration.md @@ -0,0 +1,5 @@ +# serverpod create-migration + +`serverpod create-migration` compares your current models and database definition to the last migration and writes a new migration for the difference. Run it after changing your model files. + +Use `--force` to proceed when a change may drop data, `--tag` to label the revision, or `--empty` to create a migration even when nothing has changed. For the full workflow, see [Migrations](/concepts/database/migrations). diff --git a/docs/06-concepts/cli/commands/create-migration/create-migration.mdx b/docs/06-concepts/cli/commands/create-migration/create-migration.mdx new file mode 100644 index 00000000..7dd45d20 --- /dev/null +++ b/docs/06-concepts/cli/commands/create-migration/create-migration.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_create-migration.md'; +import CreateMigration from '../../_generated/create-migration.md'; + + + + diff --git a/docs/06-concepts/cli/commands/create-repair-migration/_category_.json b/docs/06-concepts/cli/commands/create-repair-migration/_category_.json new file mode 100644 index 00000000..bf8be119 --- /dev/null +++ b/docs/06-concepts/cli/commands/create-repair-migration/_category_.json @@ -0,0 +1 @@ +{"label": "create-repair-migration"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/create-repair-migration/_create-repair-migration.md b/docs/06-concepts/cli/commands/create-repair-migration/_create-repair-migration.md new file mode 100644 index 00000000..126270c8 --- /dev/null +++ b/docs/06-concepts/cli/commands/create-repair-migration/_create-repair-migration.md @@ -0,0 +1,5 @@ +# serverpod create-repair-migration + +`serverpod create-repair-migration` builds a migration by comparing the target state to what is actually in the live database, rather than to the latest migration. Use it to bring a database back in sync when it has drifted from your migration history. + +Select which database to inspect with `--mode` (`development`, `staging`, or `production`), and target a specific version with `--version`. See [Migrations](/concepts/database/migrations). diff --git a/docs/06-concepts/cli/commands/create-repair-migration/create-repair-migration.mdx b/docs/06-concepts/cli/commands/create-repair-migration/create-repair-migration.mdx new file mode 100644 index 00000000..4c29c59e --- /dev/null +++ b/docs/06-concepts/cli/commands/create-repair-migration/create-repair-migration.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_create-repair-migration.md'; +import CreateRepairMigration from '../../_generated/create-repair-migration.md'; + + + + diff --git a/docs/06-concepts/cli/commands/create/_category_.json b/docs/06-concepts/cli/commands/create/_category_.json new file mode 100644 index 00000000..57b11c65 --- /dev/null +++ b/docs/06-concepts/cli/commands/create/_category_.json @@ -0,0 +1 @@ +{"label": "create"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/create/_create.md b/docs/06-concepts/cli/commands/create/_create.md new file mode 100644 index 00000000..320d380d --- /dev/null +++ b/docs/06-concepts/cli/commands/create/_create.md @@ -0,0 +1,5 @@ +# serverpod create + +`serverpod create` scaffolds a new Serverpod project. By default it generates a full server project with a database, a server package, a client package, and a Flutter app. + +Pass `--template mini` for a minimal project without a database, or `--template module` to create a shareable module. To set up the prerequisites first, see [Installation](../../../../04-get-started/01-installation.md). diff --git a/docs/06-concepts/cli/commands/create/create.mdx b/docs/06-concepts/cli/commands/create/create.mdx new file mode 100644 index 00000000..efc18dc1 --- /dev/null +++ b/docs/06-concepts/cli/commands/create/create.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_create.md'; +import Create from '../../_generated/create.md'; + + + + diff --git a/docs/06-concepts/cli/commands/generate/_category_.json b/docs/06-concepts/cli/commands/generate/_category_.json new file mode 100644 index 00000000..f5e2bdef --- /dev/null +++ b/docs/06-concepts/cli/commands/generate/_category_.json @@ -0,0 +1 @@ +{"label": "generate"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/generate/_generate.md b/docs/06-concepts/cli/commands/generate/_generate.md new file mode 100644 index 00000000..6e8be126 --- /dev/null +++ b/docs/06-concepts/cli/commands/generate/_generate.md @@ -0,0 +1,5 @@ +# serverpod generate + +`serverpod generate` reads your model and endpoint definitions and generates the server and client Dart code that connects them. Run it whenever you add or change a model or an endpoint. + +Pass `--watch` to regenerate automatically as you edit, or `--force` to rebuild after hand-editing generated files. For what gets generated, see [Working with endpoints](/concepts/working-with-endpoints) and [Models](/concepts/models). diff --git a/docs/06-concepts/cli/commands/generate/generate.mdx b/docs/06-concepts/cli/commands/generate/generate.mdx new file mode 100644 index 00000000..c9f73788 --- /dev/null +++ b/docs/06-concepts/cli/commands/generate/generate.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_generate.md'; +import Generate from '../../_generated/generate.md'; + + + + diff --git a/docs/06-concepts/cli/commands/language-server/_category_.json b/docs/06-concepts/cli/commands/language-server/_category_.json new file mode 100644 index 00000000..10242a38 --- /dev/null +++ b/docs/06-concepts/cli/commands/language-server/_category_.json @@ -0,0 +1 @@ +{"label": "language-server"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/language-server/_language-server.md b/docs/06-concepts/cli/commands/language-server/_language-server.md new file mode 100644 index 00000000..7d927a71 --- /dev/null +++ b/docs/06-concepts/cli/commands/language-server/_language-server.md @@ -0,0 +1,5 @@ +# serverpod language-server + +`serverpod language-server` starts a Serverpod language server that communicates over JSON-RPC 2.0. It is meant to be launched by an IDE integration rather than run directly, and it powers features like diagnostics in your model and endpoint files. + +See [Language server](/tools/lsp). diff --git a/docs/06-concepts/cli/commands/language-server/language-server.mdx b/docs/06-concepts/cli/commands/language-server/language-server.mdx new file mode 100644 index 00000000..d8634308 --- /dev/null +++ b/docs/06-concepts/cli/commands/language-server/language-server.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_language-server.md'; +import LanguageServer from '../../_generated/language-server.md'; + + + + diff --git a/docs/06-concepts/cli/commands/mcp-server/_category_.json b/docs/06-concepts/cli/commands/mcp-server/_category_.json new file mode 100644 index 00000000..9684dd54 --- /dev/null +++ b/docs/06-concepts/cli/commands/mcp-server/_category_.json @@ -0,0 +1 @@ +{"label": "mcp-server"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/mcp-server/_mcp-server.md b/docs/06-concepts/cli/commands/mcp-server/_mcp-server.md new file mode 100644 index 00000000..e8624248 --- /dev/null +++ b/docs/06-concepts/cli/commands/mcp-server/_mcp-server.md @@ -0,0 +1,5 @@ +# serverpod mcp-server + +`serverpod mcp-server` starts a Model Context Protocol bridge to the `serverpod start` runner of a server project, letting an AI assistant build, run, and inspect your server. + +The server directory is auto-detected from the current working directory. Pass `--server-dir` explicitly in monorepos that contain more than one server project. diff --git a/docs/06-concepts/cli/commands/mcp-server/mcp-server.mdx b/docs/06-concepts/cli/commands/mcp-server/mcp-server.mdx new file mode 100644 index 00000000..44ecb385 --- /dev/null +++ b/docs/06-concepts/cli/commands/mcp-server/mcp-server.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_mcp-server.md'; +import McpServer from '../../_generated/mcp-server.md'; + + + + diff --git a/docs/06-concepts/cli/commands/quickstart/_category_.json b/docs/06-concepts/cli/commands/quickstart/_category_.json new file mode 100644 index 00000000..e80d17cc --- /dev/null +++ b/docs/06-concepts/cli/commands/quickstart/_category_.json @@ -0,0 +1 @@ +{"label": "quickstart"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/quickstart/_quickstart.md b/docs/06-concepts/cli/commands/quickstart/_quickstart.md new file mode 100644 index 00000000..1e6b684f --- /dev/null +++ b/docs/06-concepts/cli/commands/quickstart/_quickstart.md @@ -0,0 +1,5 @@ +# serverpod quickstart + +`serverpod quickstart` creates a new Serverpod project with a small set of options, suited to a quick experiment or a simple app. It is a streamlined version of `serverpod create`. + +Choose between a `server` or `module` template with `--template`. For a guided first project, see [Quickstart](../../../../04-get-started/02-quickstart.md). diff --git a/docs/06-concepts/cli/commands/quickstart/quickstart.mdx b/docs/06-concepts/cli/commands/quickstart/quickstart.mdx new file mode 100644 index 00000000..43c49020 --- /dev/null +++ b/docs/06-concepts/cli/commands/quickstart/quickstart.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_quickstart.md'; +import Quickstart from '../../_generated/quickstart.md'; + + + + diff --git a/docs/06-concepts/cli/commands/run/_category_.json b/docs/06-concepts/cli/commands/run/_category_.json new file mode 100644 index 00000000..9eaa966f --- /dev/null +++ b/docs/06-concepts/cli/commands/run/_category_.json @@ -0,0 +1 @@ +{"label": "run"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/run/_run.md b/docs/06-concepts/cli/commands/run/_run.md new file mode 100644 index 00000000..94d021c9 --- /dev/null +++ b/docs/06-concepts/cli/commands/run/_run.md @@ -0,0 +1,5 @@ +# serverpod run + +`serverpod run` runs a script defined in the `serverpod/scripts` section of your `pubspec.yaml`. Pass `--list` to see the available scripts. + +See [Run scripts](/tools/run-scripts). diff --git a/docs/06-concepts/cli/commands/run/run.mdx b/docs/06-concepts/cli/commands/run/run.mdx new file mode 100644 index 00000000..348433d0 --- /dev/null +++ b/docs/06-concepts/cli/commands/run/run.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_run.md'; +import Run from '../../_generated/run.md'; + + + + diff --git a/docs/06-concepts/cli/commands/upgrade/_category_.json b/docs/06-concepts/cli/commands/upgrade/_category_.json new file mode 100644 index 00000000..074c1411 --- /dev/null +++ b/docs/06-concepts/cli/commands/upgrade/_category_.json @@ -0,0 +1 @@ +{"label": "upgrade"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/upgrade/_upgrade.md b/docs/06-concepts/cli/commands/upgrade/_upgrade.md new file mode 100644 index 00000000..d9b7ab2b --- /dev/null +++ b/docs/06-concepts/cli/commands/upgrade/_upgrade.md @@ -0,0 +1,5 @@ +# serverpod upgrade + +`serverpod upgrade` updates the Serverpod CLI to the latest version. + +For the version-specific steps when moving between major releases, see the [Upgrade to 3.5](../../../../11-upgrading/01-upgrade-to-three-five.md) guide. diff --git a/docs/06-concepts/cli/commands/upgrade/upgrade.mdx b/docs/06-concepts/cli/commands/upgrade/upgrade.mdx new file mode 100644 index 00000000..a95232b1 --- /dev/null +++ b/docs/06-concepts/cli/commands/upgrade/upgrade.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_upgrade.md'; +import Upgrade from '../../_generated/upgrade.md'; + + + + diff --git a/docs/06-concepts/cli/commands/version/_category_.json b/docs/06-concepts/cli/commands/version/_category_.json new file mode 100644 index 00000000..9ace4063 --- /dev/null +++ b/docs/06-concepts/cli/commands/version/_category_.json @@ -0,0 +1 @@ +{"label": "version"} \ No newline at end of file diff --git a/docs/06-concepts/cli/commands/version/_version.md b/docs/06-concepts/cli/commands/version/_version.md new file mode 100644 index 00000000..4cfa7c41 --- /dev/null +++ b/docs/06-concepts/cli/commands/version/_version.md @@ -0,0 +1,5 @@ +# serverpod version + +`serverpod version` prints the version of the Serverpod CLI you have installed. Include it when reporting a bug or asking for help, so the response can target your build. + +To update to the latest version, run `serverpod upgrade`. diff --git a/docs/06-concepts/cli/commands/version/version.mdx b/docs/06-concepts/cli/commands/version/version.mdx new file mode 100644 index 00000000..1ad218c2 --- /dev/null +++ b/docs/06-concepts/cli/commands/version/version.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_version.md'; +import Version from '../../_generated/version.md'; + + + + diff --git a/docs/06-concepts/cli/env_vars/_category_.json b/docs/06-concepts/cli/env_vars/_category_.json new file mode 100644 index 00000000..7b755025 --- /dev/null +++ b/docs/06-concepts/cli/env_vars/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Environment Variables", + "position": 3 +} diff --git a/docs/06-concepts/cli/env_vars/env_vars.md b/docs/06-concepts/cli/env_vars/env_vars.md new file mode 100644 index 00000000..ae8abd56 --- /dev/null +++ b/docs/06-concepts/cli/env_vars/env_vars.md @@ -0,0 +1,8 @@ +--- +title: CLI environment variables +sidebar_position: 1 +--- + +The `serverpod` command reads a single environment variable. + +`SERVERPOD_HOME` points to the Serverpod framework directory. It is only required when running the CLI in development mode, from a checkout of the Serverpod repository. A normal installation does not need it. diff --git a/docs/06-concepts/cli/global_options/_category_.json b/docs/06-concepts/cli/global_options/_category_.json new file mode 100644 index 00000000..19312943 --- /dev/null +++ b/docs/06-concepts/cli/global_options/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Global Options", + "position": 2 +} diff --git a/docs/06-concepts/cli/global_options/_global_options.md b/docs/06-concepts/cli/global_options/_global_options.md new file mode 100644 index 00000000..4c02c19c --- /dev/null +++ b/docs/06-concepts/cli/global_options/_global_options.md @@ -0,0 +1,5 @@ +# Global options + +The global options of `serverpod` can be specified anywhere on the command line, in conjunction with any command. + +They control output verbosity, analytics, interactive prompts, and experimental features. diff --git a/docs/06-concepts/cli/global_options/global_options.mdx b/docs/06-concepts/cli/global_options/global_options.mdx new file mode 100644 index 00000000..769c6151 --- /dev/null +++ b/docs/06-concepts/cli/global_options/global_options.mdx @@ -0,0 +1,9 @@ +--- +title: "" +--- +import MaintainedCommandIntro from './_global_options.md'; +import Global_options from '../_generated/global_options.md'; + + + + diff --git a/docs/06-concepts/cli/introduction/_category_.json b/docs/06-concepts/cli/introduction/_category_.json new file mode 100644 index 00000000..b9d14cd0 --- /dev/null +++ b/docs/06-concepts/cli/introduction/_category_.json @@ -0,0 +1,3 @@ +{ + "position": 1 +} diff --git a/docs/06-concepts/cli/introduction/introduction.md b/docs/06-concepts/cli/introduction/introduction.md new file mode 100644 index 00000000..738015ed --- /dev/null +++ b/docs/06-concepts/cli/introduction/introduction.md @@ -0,0 +1,41 @@ +--- +sidebar_label: Introduction +description: The Serverpod CLI reference. Every command, with the global options and environment variables that apply across all of them. +sidebar_position: 1 +--- + +# Introduction to the Serverpod CLI + +The Serverpod CLI (`serverpod`) creates projects, generates server and client code, and manages your database migrations from the command line. This reference covers every command, option, and flag. + +## Install the CLI + +Install the CLI with Dart before running any command: + +```bash +dart pub global activate serverpod_cli +``` + +See [Installation](../../../04-get-started/01-installation.md) for the full setup, including the prerequisites. + +## Command syntax + +Every `serverpod` invocation follows the same shape: + +```text +serverpod [global options] [] [arguments] [options] +``` + +Run `serverpod help` to list the commands, or `serverpod help ` for the options of a single command. + +## Global options + +A small set of options applies to every command: output verbosity (`-q` / `--quiet`, `-v` / `--verbose`), analytics (`-a` / `--analytics`), interactive prompts (`--interactive`), and experimental features (`--experimental-features`). The full list lives on the [Global options](../global_options/global_options.mdx) page. + +## Environment variables + +The CLI reads a single environment variable, described on the [Environment variables](../env_vars/env_vars.md) page. + +## How this reference is organized + +Each command page combines a hand-written introduction with the auto-generated subcommand and option listings drawn from `serverpod help`. The sidebar lists commands alphabetically. Use the search box for fast lookup by flag or argument name. diff --git a/util/generate_cli_reference.sh b/util/generate_cli_reference.sh new file mode 100755 index 00000000..d3670574 --- /dev/null +++ b/util/generate_cli_reference.sh @@ -0,0 +1,117 @@ +#!/usr/bin/env bash +# +# Generates the framework CLI reference usage blocks under +# docs/06-concepts/cli/_generated/ from the installed `serverpod` CLI. +# +# This mirrors how the Serverpod Cloud CLI reference is produced from +# `cli_tools`. Run it after installing the target CLI version: +# +# dart pub global activate serverpod_cli +# util/generate_cli_reference.sh +# +# Only the _generated/*.md files are written. The hand-maintained intros +# (_.md) and composer pages (.mdx) are not touched. + +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +OUT_DIR="$REPO_ROOT/docs/06-concepts/cli/_generated" + +COMMANDS=( + cloud + completion + create + create-migration + create-repair-migration + generate + language-server + mcp-server + quickstart + run + upgrade + version +) + +mkdir -p "$OUT_DIR" + +# Runs a command inside a wide (200-column) pseudo-terminal so the CLI's usage +# formatter does not wrap option descriptions at the default 80 columns. This +# matches the unwrapped output the Cloud reference gets from cli_tools. +pty_run() { + python3 - "$@" <<'PY' +import pty, os, struct, fcntl, termios, sys +args = sys.argv[1:] +pid, fd = pty.fork() +if pid == 0: + os.execvp(args[0], args) +fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack('HHHH', 50, 200, 0, 0)) +out = b'' +while True: + try: + data = os.read(fd, 4096) + except OSError: + break + if not data: + break + out += data +os.waitpid(pid, 0) +sys.stdout.write(out.decode(errors='replace')) +PY +} + +# Strips the shared "Global options:" block (documented on its own page) and +# trailing whitespace, keeping the command-specific usage and its internal +# spacing intact. +clean_usage() { + tr -d '\r' \ + | awk '/^Global options:/ {exit} {print}' \ + | sed -e 's/[[:space:]]*$//' \ + | awk '{a[NR]=$0} END {n=NR; while (n>0 && a[n]=="") n--; for (i=1;i<=n;i++) print a[i]}' +} + +# Lists the immediate subcommand names of a command, if any. +list_subcommands() { + pty_run serverpod help "$1" 2>&1 | tr -d '\r' \ + | awk '/Available subcommands:/ {f=1; next} /^Run "/ {f=0} f && /^ [a-z]/ {print $1}' +} + +for cmd in "${COMMANDS[@]}"; do + out="$OUT_DIR/${cmd}.md" + { + echo '## Usage' + echo + echo '```console' + pty_run serverpod help "$cmd" 2>&1 | clean_usage + echo '```' + + subs=$(list_subcommands "$cmd") + if [ -n "$subs" ]; then + echo + echo '### Sub commands' + while IFS= read -r sub; do + [ -z "$sub" ] && continue + echo + echo "#### \`$sub\`" + echo + echo '```console' + pty_run serverpod help "$cmd" "$sub" 2>&1 | clean_usage + echo '```' + done <<< "$subs" + fi + } > "$out" + echo "wrote $out" +done + +# Top-level usage, including the shared global options block and command list. +# Documented on the Global options page, so the block is kept here in full. +{ + echo '## Usage' + echo + echo '```console' + pty_run serverpod help 2>&1 | tr -d '\r' | sed -e 's/[[:space:]]*$//' \ + | awk '{a[NR]=$0} END {n=NR; while (n>0 && a[n]=="") n--; for (i=1;i<=n;i++) print a[i]}' + echo '```' +} > "$OUT_DIR/global_options.md" +echo "wrote $OUT_DIR/global_options.md" + +echo "Done. Generated ${#COMMANDS[@]} command files plus global_options.md in $OUT_DIR"