add docs for exec cli (#1849)

Add some docs for the exec cli command for go and ts.
Also deprecate the alpha version of the command and refer to using the
non-alpha version.

---------

Co-authored-by: André Eriksson <[email protected]>

Author: fredr

cli/cmd/encore/exec.go

@@ -23,6 +23,19 @@ var execCmd = &cobra.Command{
 		execScript(appRoot, wd, args)
 	},
 }
+var execCmdAlpha = &cobra.Command{
+	Use:        "exec path/to/script [args...]",
+	Short:      "Runs executable scripts against the local Encore app",
+	Hidden:     true,
+	Deprecated: "use \"encore exec\" instead",
+	Run: func(cmd *cobra.Command, args []string) {
+		if len(args) == 0 {
+			args = []string{"."} // current directory
+		}
+		appRoot, wd := determineAppRoot()
+		execScript(appRoot, wd, args)
+	},
+}
 
 func execScript(appRoot, relWD string, args []string) {
 	interrupt := make(chan os.Signal, 1)
@@ -64,6 +77,6 @@ func init() {
 
 func init() {
 	execCmd.Flags().StringVarP(&nsName, "namespace", "n", "", "Namespace to use (defaults to active namespace)")
-	alphaCmd.AddCommand(execCmd)
+	alphaCmd.AddCommand(execCmdAlpha)
 	rootCmd.AddCommand(execCmd)
 }

docs/go/cli/cli-reference.md

@@ -34,6 +34,25 @@ Checks your application for compile-time errors using Encore's compiler.
 $ encore check
 ```
 
+
+#### Exec
+
+Runs executable scripts against the local Encore app.
+
+Compiles and runs a go script with the local Encore app environment setup.
+
+```
+$ encore exec <path/to/script>
+```
+
+##### Example
+
+Run a database seed script
+
+```
+$ encore exec cmd/seed
+```
+
 ## App
 
 Commands to create and link Encore apps

docs/menu.cue

@@ -813,6 +813,11 @@
 				text: "Multithreading"
 				path: "/ts/develop/multithreading"
 				file: "ts/develop/multithreading"
+			},{
+				kind: "basic"
+				text: "Running Scripts"
+				path: "/ts/develop/running-scripts"
+				file: "ts/develop/running-scripts"
 			}]
 		},
 		{

docs/ts/cli/cli-reference.md

@@ -34,6 +34,24 @@ Checks your application for compile-time errors using Encore's compiler.
 $ encore check
 ```
 
+#### Exec
+
+Runs executable scripts against the local Encore app.
+
+Takes a command that it will execute with the local Encore app environment setup.
+
+```
+$ encore exec -- <command>
+```
+
+##### Example
+
+Run a database seed script
+
+```
+$ encore exec -- npx tsx ./seed.ts
+```
+
 ## App
 
 Commands to create and link Encore apps

docs/ts/develop/running-scripts.md

@@ -0,0 +1,50 @@
+---
+seotitle: How to use `encore exec` for running scripts
+seodesc: Learn how to use the `encore exec` command to run scripts like database seeding in your Encore app.
+title: Running Scripts
+subtitle: Run scripts with your application's infrastructure and runtime configured and initialized
+lang: ts
+---
+In local development, you may need to run scripts or commands, such as seeding a database with initial data.
+For that to work the database needs to be started, and the Encore runtime needs to be configured and initialized.
+
+## Using `encore exec`
+
+The `encore exec` command allows you to execute custom commands while leveraging Encore's infrastructure setup. This is particularly useful for tasks like database seeding, running scripts, or other one-off commands that require the app's environment to be initialized.
+
+### How it works
+
+The `encore exec` command initializes the required infrastructure for your Encore app and executes the specified command.
+This ensures that your commands run in the correct context with all dependencies properly configured.
+
+### Example: Database Seeding
+
+In this example, `npx tsx ./seed.ts` runs a TypeScript script (`seed.ts`) to populate the database with initial data
+
+```bash
+encore exec -- npx tsx ./seed.ts
+```
+
+Here’s what happens:
+1. Encore initializes the app infrastructure.
+2. The `npx tsx ./seed.ts` command is executed in the context of the initialized app.
+
+### General Syntax
+
+```bash
+encore exec -- <your-command>
+```
+
+Substitute `<your-command>` with the specific command you wish to run.
+
+### Use Cases
+
+- **Database Seeding**: Populate your database with initial data using a script.
+- **Client Generation**: Generate a client for interacting with an external dependency.
+- **Custom Scripts**: Run any script that depends on the app's initialized environment.
+
+### Notes
+
+- Ensure that the command you provide is executable in your environment.
+- Use `--` to separate `encore exec` options from the command you want to run.
+