From f54b23eddf8fbeeca6e2dd4fb7946d05181cd761 Mon Sep 17 00:00:00 2001
From: Mykal Machon <mykal@railway.com>
Date: Thu, 6 Aug 2026 13:23:12 -0700
Subject: [PATCH] Document monorepo configuration via CLI

---
 content/docs/cli/environment.md      |  9 +++++++--
 content/docs/deployments/monorepo.md | 19 +++++++++++++++++--
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/content/docs/cli/environment.md b/content/docs/cli/environment.md
index 487cb9ebd..62a7b3c13 100644
--- a/content/docs/cli/environment.md
+++ b/content/docs/cli/environment.md
@@ -109,12 +109,17 @@ The `--service-config` flag uses dot-path notation to specify nested configurati
 # Set a variable value
 railway environment edit --service-config backend variables.API_KEY.value "secret"
 
-# Set a service configuration
-railway environment edit --service-config api buildCommand "npm run build"
+# Set a build command
+railway environment edit --service-config api build.buildCommand "npm run build"
+
+# Set a monorepo root directory
+railway environment edit --service-config api source.rootDirectory /packages/api
 ```
 
 The format is: `--service-config <SERVICE_NAME> <DOT.PATH.TO.PROPERTY> <VALUE>`
 
+For more information about configuring monorepo services, see [Deploying a monorepo](/deployments/monorepo).
+
 ## Options for `config`
 
 | Flag | Description |
diff --git a/content/docs/deployments/monorepo.md b/content/docs/deployments/monorepo.md
index fd26befcb..c67d1445f 100644
--- a/content/docs/deployments/monorepo.md
+++ b/content/docs/deployments/monorepo.md
@@ -31,6 +31,12 @@ To deploy this type of monorepo on Railway, define a root directory for the serv
 2. Click on the Settings tab.
 3. Set the root directory option. Setting this means that Railway will only pull down files from that directory when creating new deployments.
 
+Alternatively, set the root directory from the CLI:
+
+```bash
+railway environment edit --service-config backend source.rootDirectory /backend
+```
+
 <Image
 src="https://res.cloudinary.com/railway/image/upload/v1637798659/docs/root-directory_achzga.png"
 alt="Screenshot of root directory configuration"
@@ -64,6 +70,15 @@ codebase.
 2. Click on the Settings tab.
 3. Set the start command, e.g. `npm run start:backend` and `npm run start:frontend`
 
+If you prefer, you can set custom build and start commands from the CLI:
+
+```bash
+railway environment edit \
+  --service-config backend build.buildCommand "pnpm --filter backend build"
+railway environment edit \
+  --service-config backend deploy.startCommand "pnpm --filter backend start"
+```
+
 <Image
 src="https://res.cloudinary.com/railway/image/upload/v1637798815/docs/custom-start-command_a8vcxs.png"
 alt="Screenshot of custom start command configuration"
@@ -112,6 +127,6 @@ A monorepo might want to only trigger builds if files are changed in the `/packa
 
 ## Using the CLI
 
-When interacting with your services deployed from a monorepo using the CLI, always ensure you are "linked" to the appropriate service when executing commands.
+The Railway CLI lets you configure a service's root directory, build command, and start command with [`railway environment edit`](/cli/environment). Use the `--service-config` flag with the corresponding dot-path.
 
-To link to a specific service from the CLI, use `railway link` and follow the prompts.
+Before running the command, use `railway link` and follow the prompts to link the CLI to the correct project and environment. The `--service-config` flag selects the target service by name or ID.