Add astro preferences CLI reference (#5512)

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
withastro · Jan 26, 2024 · 3e9f742 · 3e9f742
1 parent 46d16b9
commit 3e9f742
Showing 1 changed file with 39 additions and 0 deletions.
diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx
@@ -70,6 +70,7 @@ Commands
              info  List info about your current Astro setup.
           preview  Preview your build locally.
              sync  Generate content collection types.
+      preferences  Configure user preferences.
         telemetry  Configure telemetry settings.
 
 Global Flags
@@ -287,6 +288,44 @@ Adapter                  @astrojs/vercel/serverless
 Integrations             none
 ```
 
+## `astro preferences`
+
+Manage user preferences with the `astro preferences` command. User preferences are specific to individual Astro users, unlike the `astro.config.mjs` file which changes behavior for everyone working on a project.
+
+User preferences are scoped to the current project by default, stored in a local `.astro/settings.json` file.
+
+Using the `--global` flag, user preferences can also be applied to every Astro project on the current machine. Global user preferences are stored in an operating system-specific location.
+
+For example, to disable the devToolbar in a specific Astro project:
+
+```shell
+astro preferences disable devToolbar
+```
+
+To disable the devToolbar in all Astro projects on the current machine:
+
+```shell
+astro preferences disable --global devToolbar
+```
+
+The devToolbar can later be enabled with:
+
+```shell
+astro preferences enable devToolbar
+```
+
+The `reset` command resets a preference to its default value:
+
+```shell
+astro preferences reset devOverlay
+```
+
+The `list` command prints the current settings of all configurable user preferences. It also supports a machine-readable `--json` output.
+
+```shell
+astro preferences list
+```
+
 ## `astro telemetry`
 
 Sets telemetry configuration for the current CLI user. Telemetry is anonymous data that provides the Astro team insights into which Astro features are most often used. For more information see [Astro's telemetry page](https://astro.build/telemetry/).