From 4ad50dc4ac7ef6665764328a2a4f5a04278c691a Mon Sep 17 00:00:00 2001 From: Gaetan SENN Date: Mon, 16 Mar 2026 11:13:51 +0100 Subject: [PATCH 1/5] feat: add cli cache clear command --- content/configuration/cache.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/content/configuration/cache.md b/content/configuration/cache.md index 71573dcf..9b4df958 100644 --- a/content/configuration/cache.md +++ b/content/configuration/cache.md @@ -63,3 +63,31 @@ benefits on quick subsequent reads. [5] `CACHE_STORE` For larger projects, you most likely don't want to rely on local memory for caching. Instead, you can use the above `CACHE_STORE` environment variable to use `redis` as the cache store. + +## Clearing the Cache + +Use the `cache clear` CLI command to flush both the data cache and the system cache (schema, permissions, etc.). + +```sh +npx directus cache clear +``` + +This command reads the same cache configuration as the running Directus instance (`CACHE_STORE`, `CACHE_NAMESPACE`, and any Redis connection variables). Run it with the same environment variables your Directus instance uses. + +::callout{icon="material-symbols:info-outline"} +If you use `memory` as `CACHE_STORE`, this command has no effect - in-memory caches are local to each running process and can only be cleared by restarting the instance. +:: + +### Usage in CI/CD Pipelines + +Directus does not automatically clear the cache on startup. If your deploy pipeline applies migrations or schema changes, running instances will continue to serve stale cached data until the TTL expires. Run `cache clear` as the last step to avoid this: + +```sh +npx directus database migrate:latest +npx directus schema apply ./path/to/snapshot.yaml +npx directus cache clear +``` + +::callout{icon="material-symbols:warning-rounded" color="warning"} +In a horizontal scaling setup with a shared cache store like Redis, this command flushes the cache for all instances at once. All instances will rebuild their cache on the next request, which may cause a temporary increase in database load. +:: From 214f4a2b57c4407aa872a31a03c50b3d9483cd62 Mon Sep 17 00:00:00 2001 From: Gaetan SENN Date: Mon, 16 Mar 2026 15:28:41 +0100 Subject: [PATCH 2/5] feat: add flag options --- content/configuration/cache.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/content/configuration/cache.md b/content/configuration/cache.md index 9b4df958..f60587a0 100644 --- a/content/configuration/cache.md +++ b/content/configuration/cache.md @@ -74,6 +74,18 @@ npx directus cache clear This command reads the same cache configuration as the running Directus instance (`CACHE_STORE`, `CACHE_NAMESPACE`, and any Redis connection variables). Run it with the same environment variables your Directus instance uses. +### Selective Clearing + +By default, `cache clear` flushes both caches. Use flags to target a specific cache: + +- `--system` - Clears only the system cache (schema, permissions, etc.) +- `--data` - Clears only the data cache + +```sh +npx directus cache clear --system +npx directus cache clear --data +``` + ::callout{icon="material-symbols:info-outline"} If you use `memory` as `CACHE_STORE`, this command has no effect - in-memory caches are local to each running process and can only be cleared by restarting the instance. :: From 9539e80ebb0f61ad42026f4a9c71b051379bb6f8 Mon Sep 17 00:00:00 2001 From: Gaetan SENN Date: Mon, 16 Mar 2026 17:46:11 +0100 Subject: [PATCH 3/5] refactor: simplify cli part --- content/configuration/cache.md | 30 +++--------------------------- 1 file changed, 3 insertions(+), 27 deletions(-) diff --git a/content/configuration/cache.md b/content/configuration/cache.md index f60587a0..05ae5098 100644 --- a/content/configuration/cache.md +++ b/content/configuration/cache.md @@ -66,40 +66,16 @@ Instead, you can use the above `CACHE_STORE` environment variable to use `redis` ## Clearing the Cache -Use the `cache clear` CLI command to flush both the data cache and the system cache (schema, permissions, etc.). +Use the `cache clear` CLI command to manually clear the cache. By default, it flushes both the data cache and the system cache (schema, permissions, etc.). Use `--system` or `--data` to target a specific cache. ```sh npx directus cache clear -``` - -This command reads the same cache configuration as the running Directus instance (`CACHE_STORE`, `CACHE_NAMESPACE`, and any Redis connection variables). Run it with the same environment variables your Directus instance uses. - -### Selective Clearing - -By default, `cache clear` flushes both caches. Use flags to target a specific cache: - -- `--system` - Clears only the system cache (schema, permissions, etc.) -- `--data` - Clears only the data cache - -```sh npx directus cache clear --system npx directus cache clear --data ``` +This command reads the same cache configuration as the running Directus instance (`CACHE_STORE`, `CACHE_NAMESPACE`, and any Redis connection variables). Run it with the same environment variables your Directus instance uses. + ::callout{icon="material-symbols:info-outline"} If you use `memory` as `CACHE_STORE`, this command has no effect - in-memory caches are local to each running process and can only be cleared by restarting the instance. :: - -### Usage in CI/CD Pipelines - -Directus does not automatically clear the cache on startup. If your deploy pipeline applies migrations or schema changes, running instances will continue to serve stale cached data until the TTL expires. Run `cache clear` as the last step to avoid this: - -```sh -npx directus database migrate:latest -npx directus schema apply ./path/to/snapshot.yaml -npx directus cache clear -``` - -::callout{icon="material-symbols:warning-rounded" color="warning"} -In a horizontal scaling setup with a shared cache store like Redis, this command flushes the cache for all instances at once. All instances will rebuild their cache on the next request, which may cause a temporary increase in database load. -:: From 9079ecec94ccb97691742a92adbc1acdaefc128f Mon Sep 17 00:00:00 2001 From: Gaetan SENN Date: Tue, 17 Mar 2026 10:37:46 +0100 Subject: [PATCH 4/5] refactor: add new cli page --- content/configuration/cache.md | 14 +--- content/configuration/cli.md | 109 ++++++++++++++++++++++++++++ content/configuration/migrations.md | 13 +--- 3 files changed, 111 insertions(+), 25 deletions(-) create mode 100644 content/configuration/cli.md diff --git a/content/configuration/cache.md b/content/configuration/cache.md index 05ae5098..a7cac3ea 100644 --- a/content/configuration/cache.md +++ b/content/configuration/cache.md @@ -66,16 +66,4 @@ Instead, you can use the above `CACHE_STORE` environment variable to use `redis` ## Clearing the Cache -Use the `cache clear` CLI command to manually clear the cache. By default, it flushes both the data cache and the system cache (schema, permissions, etc.). Use `--system` or `--data` to target a specific cache. - -```sh -npx directus cache clear -npx directus cache clear --system -npx directus cache clear --data -``` - -This command reads the same cache configuration as the running Directus instance (`CACHE_STORE`, `CACHE_NAMESPACE`, and any Redis connection variables). Run it with the same environment variables your Directus instance uses. - -::callout{icon="material-symbols:info-outline"} -If you use `memory` as `CACHE_STORE`, this command has no effect - in-memory caches are local to each running process and can only be cleared by restarting the instance. -:: +Use the [`cache clear`](/configuration/cli#clear) CLI command to manually flush the data cache, system cache, or both. This is useful in CI/CD pipelines after applying migrations or schema changes. diff --git a/content/configuration/cli.md b/content/configuration/cli.md new file mode 100644 index 00000000..bf46395e --- /dev/null +++ b/content/configuration/cli.md @@ -0,0 +1,109 @@ +--- +title: CLI +description: Built-in Directus CLI commands. +--- + +Directus includes several CLI commands for managing your instance. All commands are run via +`npx directus `. + +## Start + +Starts the Directus server. + +```sh +npx directus start +``` + +You can override the configuration file path by setting `CONFIG_PATH`: + +```sh +CONFIG_PATH="/path/to/config.js" npx directus start +``` + +See [Configuration Options](/configuration/intro) for supported file formats. + +## Bootstrap + +Prepares the database for use by Directus. This runs `database install`, `database migrate:latest`, and creates the +initial admin user if one does not exist. + +```sh +npx directus bootstrap +``` + +This is the recommended command when setting up a new Directus project. If you need more control over individual steps, +use the commands below instead. + +## Database + +### Install + +Installs the required Directus system tables into the database. + +```sh +npx directus database install +``` + +### Migrate + +Runs all pending Directus internal migrations and any custom migrations from the configured `MIGRATIONS_PATH` directory. + +```sh +npx directus database migrate:latest +``` + +See [Migrations](/configuration/migrations) for details on writing custom migration files. + +## Schema + +### Apply + +Applies a schema snapshot to the Directus instance. Use this to synchronize your data model across environments. + +```sh +npx directus schema apply ./path/to/snapshot.yaml +``` + +## Cache + +### Clear + +Clears the Directus cache. By default, it flushes both the data cache and the system cache (schema, permissions, etc.). +This command reads the same cache configuration as the running Directus instance (`CACHE_STORE`, `CACHE_NAMESPACE`, and +any Redis connection variables). Run it with the same environment variables your Directus instance uses. + +```sh +npx directus cache clear +``` + +Use flags to target a specific cache: + +| Flag | Description | +| ---------- | -------------------------------------------------- | +| `--system` | Clears only the system cache (schema, permissions) | +| `--data` | Clears only the data cache | + +::callout{icon="material-symbols:info-outline"} +If you use `memory` as `CACHE_STORE`, this command has no effect. In-memory caches are local to each running process and +can only be cleared by restarting the instance. +:: + +Directus does not automatically clear the cache on startup. If your deploy pipeline applies migrations or schema +changes, running instances will continue to serve stale cached data until the TTL expires. Run `cache clear` as the last +step to avoid this: + +```sh +npx directus bootstrap +npx directus schema apply ./path/to/snapshot.yaml +npx directus cache clear +``` + +::callout{icon="material-symbols:warning-rounded" color="warning"} +In a horizontal scaling setup with a shared cache store like Redis, this command flushes the cache for all instances at +once. All instances will rebuild their cache on the next request, which may cause a temporary increase in database load. +:: + +## Extension CLI + +For commands related to building, validating, and managing extensions, see the +[Extension CLI](/guides/extensions/cli) documentation. diff --git a/content/configuration/migrations.md b/content/configuration/migrations.md index 38e06b68..a69f07b8 100644 --- a/content/configuration/migrations.md +++ b/content/configuration/migrations.md @@ -39,17 +39,6 @@ Proceed at your own risk and backup your database before adding custom migration Migrations can be used to manage the contents of Directus collections (e.g. initial hydration). In order to do it, you must ensure that the schema is up to date before running your migrations. -`directus database migrate:latest` runs the required Directus internal migrations and the migrations from the `migrations` directory. In general, you need the following flow: - -```sh -# Option 1 -npx directus bootstrap -npx directus schema apply ./path/to/snapshot.yaml - -# Option 2 - without bootstrap, you must ensure that you run all required `bootstrap` tasks -npx directus database install -npx directus database migrate:latest -npx directus schema apply ./path/to/snapshot.yaml -``` +`directus database migrate:latest` runs the required Directus internal migrations and the migrations from the `migrations` directory. See the [CLI documentation](/configuration/cli#database) for the full setup flow using `bootstrap`, `database install`, `database migrate:latest`, and `schema apply`. To correctly follow this process, the `migrations` directory must not contain tasks that modify the contents of Directus system collections, because schema may not yet be created when you run `migrate:latest`. From 766ef132648579dd03db0fdc811171208f281308 Mon Sep 17 00:00:00 2001 From: Gaetan SENN Date: Tue, 17 Mar 2026 11:02:47 +0100 Subject: [PATCH 5/5] feat: add help option --- content/configuration/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/configuration/cli.md b/content/configuration/cli.md index bf46395e..58a5aae2 100644 --- a/content/configuration/cli.md +++ b/content/configuration/cli.md @@ -4,7 +4,7 @@ description: Built-in Directus CLI commands. --- Directus includes several CLI commands for managing your instance. All commands are run via -`npx directus `. +`npx directus `. You can append `--help` to any command to see its available options. ## Start