Add CLI multi-file configuration docs

src/routes/changelog/(entries)/2026-05-06.markdoc

@@ -0,0 +1,28 @@
+---
+layout: changelog
+title: "Appwrite CLI now supports multi-file project configuration"
+date: 2026-05-06
+cover:
+---
+
+Appwrite CLI 20.0.0 adds support for splitting large `appwrite.config.json` files into multiple local JSON files with a new `includes` field.
+
+You can move supported resource arrays, such as functions, sites, tablesDB, tables, topics, teams, buckets, webhooks, and messages, into their own files while keeping `init`, `pull`, `push`, and `run` workflows unchanged. The CLI reads included resources into the same in-memory config shape and writes updates back to the file where each resource is defined.
+
+Function and site paths are resolved relative to the file that defines them, so nested workspaces, packages, and submodules can keep resource configuration and source paths together.
+
+```json
+{
+    "projectId": "<PROJECT_ID>",
+    "endpoint": "https://<REGION>.cloud.appwrite.io/v1",
+    "includes": {
+        "functions": "./appwrite/functions.json",
+        "sites": "./appwrite/sites.json",
+        "buckets": "./appwrite/buckets.json"
+    }
+}
+```
+
+{% arrow_link href="/docs/tooling/command-line/installation#multi-file-configuration" %}
+Learn more about multi-file configuration
+{% /arrow_link %}

src/routes/docs/products/functions/deploy-manually/+page.markdoc

@@ -22,6 +22,8 @@ you can do so by editing the `appwrite.config.json` file.
 Learn more about appwrite.config.json
 {% /arrow_link %}
 
+For larger projects, you can split function definitions into a separate JSON file with [multi-file CLI configuration](/docs/tooling/command-line/installation#multi-file-configuration).
+
 # Manual Deployment {% #manual %} 
 
 You can upload your functions to be deployed using the Appwrite Console. The example below shows a simple Node.js function.

src/routes/docs/products/sites/deploy-from-cli/+page.markdoc

@@ -20,6 +20,8 @@ you can do so by editing the `appwrite.config.json` file.
 Learn more about appwrite.config.json
 {% /arrow_link %}
 
+For larger projects, you can split site definitions into a separate JSON file with [multi-file CLI configuration](/docs/tooling/command-line/installation#multi-file-configuration).
+
 # Debugging
 
-- If you updated your site's configuration but the deployment is not working as expected, you may need to first redeploy your site before the changes take effect.
+- If you updated your site's configuration but the deployment is not working as expected, you may need to first redeploy your site before the changes take effect.

src/routes/docs/tooling/command-line/buckets/+page.markdoc

@@ -56,6 +56,12 @@ After [initializing](/docs/tooling/command-line/installation#initialization) you
 }
 ```
 
+You can also move the `buckets` array into a separate JSON file with the `includes` field.
+
+{% arrow_link href="/docs/tooling/command-line/installation#multi-file-configuration" %}
+Learn more about multi-file configuration
+{% /arrow_link %}
+
 # Push bucket {% #push-bucket %}
 
 {% partial file="cli-push-command.md" /%}
@@ -115,4 +121,4 @@ appwrite storage [COMMAND] [OPTIONS]
 * `get-file-view [options]`
 *  Get a file content by its unique ID. This endpoint is similar to the download method but returns with no  'Content-Disposition: attachment' header.
 ---
-{% /table %}
+{% /table %}

src/routes/docs/tooling/command-line/commands/+page.markdoc

@@ -84,6 +84,8 @@ Below is a list of the available commands in the Appwrite CLI. You can get more
 ---
 {% /table %}
 
+The `init`, `pull`, `push`, and `run` commands support [multi-file project configuration](/docs/tooling/command-line/installation#multi-file-configuration). Use the `includes` field in `appwrite.config.json` to move supported resource arrays into separate JSON files while keeping CLI behavior unchanged.
+
 ## Project commands {% #appwrite-project-commands %}
 
 {% table %}
@@ -311,4 +313,4 @@ appwrite databases create-row \
     --database-id "<DATABASE_ID>" --table-id "<TABLE_ID>" \
     --row-id 'unique()' --data '{ "Name": "Iron Man" }' \
     --permissions 'read("any")' 'write("team:abc")' 
-```
+```

src/routes/docs/tooling/command-line/functions/+page.markdoc

@@ -101,6 +101,12 @@ After [initializing](/docs/tooling/command-line/installation#initialization) you
 }
 ```
 
+You can also move the `functions` array into a separate JSON file with the `includes` field. When functions are loaded from an included file, each function `path` is resolved relative to that included file.
+
+{% arrow_link href="/docs/tooling/command-line/installation#multi-file-configuration" %}
+Learn more about multi-file configuration
+{% /arrow_link %}
+
 # Push function {% #push-function %}
 
 {% partial file="cli-push-command.md" /%}
@@ -181,4 +187,4 @@ appwrite functions [COMMAND] [OPTIONS]
 * `delete-variable [options]`
 * Delete a variable by its unique ID.
 ---
-{% /table %}
+{% /table %}

src/routes/docs/tooling/command-line/installation/+page.markdoc

@@ -153,6 +153,61 @@ You can run your first CLI command after logging in. Try fetching information ab
 appwrite projects get --project-id "<PROJECT_ID>"
 ```
 
+# Multi-file configuration {% #multi-file-configuration %}
+
+By default, the Appwrite CLI stores your project settings and resource definitions in one `appwrite.config.json` file. In CLI version 20.0.0 and later, you can split top-level resource arrays into separate JSON files with the `includes` field.
+
+Use this when your project has many functions, sites, buckets, teams, topics, tables, or other deployable resources and you want to keep each resource type in its own file.
+
+```json
+{
+    "projectId": "<PROJECT_ID>",
+    "endpoint": "https://<REGION>.cloud.appwrite.io/v1",
+    "includes": {
+        "functions": "./appwrite/functions.json",
+        "sites": "./appwrite/sites.json",
+        "buckets": "./appwrite/buckets.json",
+        "teams": "./appwrite/teams.json",
+        "topics": "./appwrite/topics.json"
+    }
+}
+```
+
+Each included file contains the JSON array that would normally live under that key in `appwrite.config.json`.
+
+```json
+[
+    {
+        "$id": "<FUNCTION_ID>",
+        "name": "api",
+        "runtime": "node-22",
+        "path": "functions/api",
+        "entrypoint": "src/main.js",
+        "commands": "npm install",
+        "execute": [],
+        "events": [],
+        "schedule": "",
+        "timeout": 15,
+        "enabled": true,
+        "logging": true,
+        "ignore": [
+            "node_modules",
+            ".git"
+        ],
+        "scopes": [],
+        "vars": []
+    }
+]
+```
+
+The CLI resolves resource paths relative to the file that defines the resource. For example, if `functions` is included from `./appwrite/functions.json`, the function `path` above resolves from `./appwrite/`, not from the folder that contains the root `appwrite.config.json`.
+
+The single-file format continues to work. You can split any supported resource arrays over time and keep other arrays in the root config.
+
+Supported include keys are `functions`, `sites`, `databases`, `collections`, `tablesDB`, `tables`, `topics`, `teams`, `buckets`, `webhooks`, and `messages`.
+
+Include paths must be local JSON files inside your project. They must be relative paths, end in `.json`, and cannot use parent-directory segments, absolute paths, URLs, URL-like schemes, null bytes, or JSON pointer fragments.
+
 {% info title="Self-signed certificates" %}
 By default, requests to domains with self-signed SSL certificates (or no certificates) are disabled. If you trust the domain, you can bypass the certificate validation using
 

src/routes/docs/tooling/command-line/sites/+page.markdoc

@@ -53,6 +53,12 @@ After [initializing](/docs/tooling/command-line/installation#initialization) you
 }
 ```
 
+You can also move the `sites` array into a separate JSON file with the `includes` field. When sites are loaded from an included file, each site `path` is resolved relative to that included file.
+
+{% arrow_link href="/docs/tooling/command-line/installation#multi-file-configuration" %}
+Learn more about multi-file configuration
+{% /arrow_link %}
+
 # Push site {% #push-site %}
 
 {% partial file="cli-push-command.md" /%}
@@ -160,4 +166,4 @@ appwrite sites [COMMAND] [OPTIONS]
 * `delete-variable [options]`
 * Delete a variable by its unique ID.
 ---
-{% /table %}
+{% /table %}

src/routes/docs/tooling/command-line/tables/+page.markdoc

@@ -132,6 +132,12 @@ After [initializing](/docs/tooling/command-line/installation#initialization) you
 }
 ```
 
+You can also move the `tablesDB` and `tables` arrays into separate JSON files with the `includes` field.
+
+{% arrow_link href="/docs/tooling/command-line/installation#multi-file-configuration" %}
+Learn more about multi-file configuration
+{% /arrow_link %}
+
 # Push table {% #push-table %}
 
 {% partial file="cli-push-command.md" /%}

src/routes/docs/tooling/command-line/teams/+page.markdoc

@@ -51,6 +51,12 @@ After [initializing](/docs/tooling/command-line/installation#initialization) you
 }
 ```
 
+You can also move the `teams` array into a separate JSON file with the `includes` field.
+
+{% arrow_link href="/docs/tooling/command-line/installation#multi-file-configuration" %}
+Learn more about multi-file configuration
+{% /arrow_link %}
+
 # Push team {% #push-teams %}
 
 {% partial file="cli-push-command.md" /%}
@@ -113,4 +119,4 @@ appwrite teams [COMMAND] [OPTIONS]
 * `update-prefs [options]`             
 * Update the team's preferences by its unique ID. The object you pass is stored as is and replaces any previous value. The maximum allowed prefs size is 64kB and throws an error if exceeded.
 ---
-{% /table %}
+{% /table %}

src/routes/docs/tooling/command-line/topics/+page.markdoc

@@ -62,6 +62,12 @@ After [initializing](/docs/tooling/command-line/installation#initialization) you
 }
 ```
 
+You can also move the `topics` array into a separate JSON file with the `includes` field.
+
+{% arrow_link href="/docs/tooling/command-line/installation#multi-file-configuration" %}
+Learn more about multi-file configuration
+{% /arrow_link %}
+
 # Push topics {% #push-topics %}
 
 {% partial file="cli-push-command.md" /%}
@@ -219,4 +225,4 @@ appwrite messaging [COMMAND] [OPTIONS]
 * `delete-subscriber [options]`
 * Delete a subscriber by its unique ID.
 ---
-{% /table %}
+{% /table %}