feat: update and upgrade commands

docs/cli/index.md

@@ -8,21 +8,23 @@ You can run the CLI using `npx quartz`.
 
 ## Quick Reference
 
-| Command  | Description                           | Example                  |
+| Command   | Description                           | Example                  |
-| -------- | ------------------------------------- | ------------------------ |
+| --------- | ------------------------------------- | ------------------------ |
-| `create` | Initialize a new Quartz project       | `npx quartz create`      |
+| `create`  | Initialize a new Quartz project       | `npx quartz create`      |
-| `build`  | Generate static HTML files            | `npx quartz build`       |
+| `build`   | Generate static HTML files            | `npx quartz build`       |
-| `sync`   | Sync content with GitHub              | `npx quartz sync`        |
+| `sync`    | Sync content with GitHub              | `npx quartz sync`        |
-| `update` | Update Quartz to the latest version   | `npx quartz update`      |
+| `upgrade` | Upgrade Quartz to the latest version  | `npx quartz upgrade`     |
-| `plugin` | Manage Quartz plugins                 | `npx quartz plugin list` |
+| `update`  | Update installed plugins              | `npx quartz update`      |
-| `tui`    | Launch the interactive plugin manager | `npx quartz tui`         |
+| `plugin`  | Manage Quartz plugins                 | `npx quartz plugin list` |
+| `tui`     | Launch the interactive plugin manager | `npx quartz tui`         |
 
 ## Commands
 
 - [[cli/create|create]]: Initialize a new Quartz project from scratch or an existing vault.
 - [[cli/build|build]]: Build your Quartz site into static HTML. Includes a development server.
 - [[cli/sync|sync]]: Push and pull changes between your local machine and GitHub.
-- [[cli/update|update]]: Pull the latest changes from the official Quartz repository.
+- [[cli/upgrade|upgrade]]: Upgrade the Quartz framework to the latest version.
+- [[cli/update|update]]: Update installed plugins to their latest versions.
 - [[cli/restore|restore]]: Recover your content folder from the local cache.
 - [[cli/migrate|migrate]]: Convert older configuration files to the new YAML format.
 - [[cli/plugin|plugin]]: Install, add, remove, and configure plugins from the command line.

docs/cli/restore.md

@@ -8,7 +8,7 @@ The `restore` command is a safety mechanism that allows you to recover your cont
 
 You should use `restore` if:
 
-- A `quartz update` failed and corrupted your content.
+- A `quartz upgrade` failed and corrupted your content.
 - You accidentally deleted files in your content folder.
 - You encountered complex merge conflicts that you want to undo.
 

docs/cli/update.md

@@ -2,28 +2,37 @@
 title: quartz update
 ---
 
-The `update` command keeps your Quartz installation up to date with the latest features and bug fixes from the official repository.
+The `update` command updates your installed plugins to their latest versions. It is a convenient shortcut for `npx quartz plugin update`.
 
-## How it Works
+## Usage
 
-When you run `npx quartz update`, Quartz attempts to pull the latest code from the upstream Quartz repository. It uses Git to merge these changes into your local project.
+Update all installed plugins:
 
 ```shell
 npx quartz update
 ```
 
-## Handling Conflicts
+Update specific plugins by name:
 
-Because Quartz allows you to customize almost every part of the code, updates can sometimes result in merge conflicts. This happens if you have modified a file that the Quartz team has also updated.
+```shell
+npx quartz update my-plugin another-plugin
+```
 
-If a conflict occurs:
+## How it Works
 
-1. Git will mark the conflicting sections in the affected files.
+For each plugin, `update` fetches the latest commit from the plugin's remote repository and rebuilds it. The lockfile (`quartz.lock.json`) is updated with the new commit hashes.
-2. You will need to open these files and manually choose which changes to keep.
-3. After resolving the conflicts, you can commit the changes.
 
-## Recovery
+This is functionally identical to running:
 
-If an update goes wrong or leaves your project in an unusable state, you can use the [[cli/restore|restore]] command to recover your content from the local cache.
+```shell
+npx quartz plugin update
+```
 
-For a more detailed guide on the upgrading process, see [[getting-started/upgrading]].
+## Flags
+
+The `update` command supports the standard [[cli/index|common flags]] (`--directory`, `--verbose`).
+
+## See Also
+
+- [[cli/upgrade|quartz upgrade]] — upgrade the Quartz framework itself
+- [[cli/plugin|quartz plugin]] — full plugin management (install, remove, enable, disable, etc.)

docs/cli/upgrade.md

@@ -0,0 +1,46 @@
+---
+title: quartz upgrade
+---
+
+The `upgrade` command upgrades the Quartz framework itself to the latest version by pulling changes from the official Quartz repository.
+
+## Usage
+
+```shell
+npx quartz upgrade
+```
+
+## How it Works
+
+When you run `npx quartz upgrade`, Quartz performs the following steps:
+
+1. **Backs up your content** — your content folder is cached locally to prevent data loss.
+2. **Pulls the latest Quartz code** — fetches and merges from the official upstream repository (`upstream/v5`) using Git.
+3. **Shows version changes** — displays the version transition (e.g., `v5.0.0 → v5.1.0`) or confirms you're already up to date.
+4. **Updates dependencies** — runs `npm install` to ensure all packages match the new version.
+5. **Restores plugins** — reinstalls plugins from `quartz.lock.json` to ensure compatibility.
+6. **Checks plugin compatibility** — verifies that installed plugins are compatible with the new Quartz version.
+
+## Handling Conflicts
+
+Because Quartz allows you to customize almost every part of the code, upgrades can sometimes result in merge conflicts. This happens if you have modified a file that the Quartz team has also updated.
+
+If a conflict occurs:
+
+1. Git will mark the conflicting sections in the affected files.
+2. You will need to open these files and manually choose which changes to keep.
+3. After resolving the conflicts, you can commit the changes.
+
+## Recovery
+
+If an upgrade goes wrong or leaves your project in an unusable state, you can use the [[cli/restore|restore]] command to recover your content from the local cache.
+
+## Flags
+
+The `upgrade` command supports the standard [[cli/index|common flags]] (`--directory`, `--verbose`).
+
+## See Also
+
+- [[cli/update|quartz update]] — update installed plugins
+- [[getting-started/upgrading|Upgrading Quartz]] — detailed upgrading guide
+- [[cli/restore|quartz restore]] — recover content from cache

docs/getting-started/upgrading.md

@@ -9,13 +9,21 @@ aliases:
 
 To fetch the latest Quartz updates, simply run
 
+```bash
+npx quartz upgrade
+```
+
+As Quartz uses [git](https://git-scm.com/) under the hood for versioning, upgrading effectively 'pulls' in the updates from the official Quartz GitHub repository. If you have local changes that might conflict with the updates, you may need to resolve these manually yourself (or, pull manually using `git pull origin upstream`).
+
+> [!hint]
+> Quartz will try to cache your content before upgrading to try and prevent merge conflicts. If you get a conflict mid-merge, you can stop the merge and then run `npx quartz restore` to restore your content from the cache.
+
+If you have the [GitHub desktop app](https://desktop.github.com/), this will automatically open to help you resolve the conflicts. Otherwise, you will need to resolve this in a text editor like VSCode. For more help on resolving conflicts manually, check out the [GitHub guide on resolving merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line#competing-line-change-merge-conflicts).
+
+To update your installed plugins separately, use:
+
 ```bash
 npx quartz update
 ```
 
-As Quartz uses [git](https://git-scm.com/) under the hood for versioning, updating effectively 'pulls' in the updates from the official Quartz GitHub repository. If you have local changes that might conflict with the updates, you may need to resolve these manually yourself (or, pull manually using `git pull origin upstream`).
+See the [[cli/update|CLI reference for update]] and [[cli/upgrade|CLI reference for upgrade]] for more details on available flags.
-
-> [!hint]
-> Quartz will try to cache your content before updating to try and prevent merge conflicts. If you get a conflict mid-merge, you can stop the merge and then run `npx quartz restore` to restore your content from the cache.
-
-If you have the [GitHub desktop app](https://desktop.github.com/), this will automatically open to help you resolve the conflicts. Otherwise, you will need to resolve this in a text editor like VSCode. For more help on resolving conflicts manually, check out the [GitHub guide on resolving merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line#competing-line-change-merge-conflicts).

docs/troubleshooting.md

@@ -18,7 +18,7 @@ This restores all plugins from your `quartz.lock.json` to `.quartz/plugins/`.
 
 ### `tsc` type errors after updating
 
-After running `npx quartz update`, type errors can occur if the update changed internal APIs that your `quartz.ts` overrides depend on. Check the changelog for breaking changes and update your overrides accordingly.
+After running `npx quartz upgrade`, type errors can occur if the update changed internal APIs that your `quartz.ts` overrides depend on. Check the changelog for breaking changes and update your overrides accordingly.
 
 ### Build is slow
 

quartz/bootstrap-cli.mjs

@@ -5,6 +5,7 @@ import {
   handleBuild,
   handleCreate,
   handleUpdate,
+  handleUpgrade,
   handleRestore,
   handleSync,
 } from "./cli/handlers.js"
@@ -80,8 +81,16 @@ yargs(hideBin(process.argv))
   .command("create", "Initialize Quartz", CreateArgv, async (argv) => {
     await handleCreate(argv)
   })
-  .command("update", "Get the latest Quartz updates", CommonArgv, async (argv) => {
+  .command(
-    await handleUpdate(argv)
+    "update [names..]",
+    "Update installed plugins to latest version",
+    CommonArgv,
+    async (argv) => {
+      await handleUpdate(argv)
+    },
+  )
+  .command("upgrade", "Upgrade Quartz to the latest version", CommonArgv, async (argv) => {
+    await handleUpgrade(argv)
   })
   .command(
     "restore",

quartz/cli/handlers.js

@@ -23,7 +23,11 @@ import {
   popContentFolder,
   stashContentFolder,
 } from "./helpers.js"
-import { handlePluginRestore, handlePluginCheck } from "./plugin-git-handlers.js"
+import {
+  handlePluginRestore,
+  handlePluginCheck,
+  handlePluginUpdate,
+} from "./plugin-git-handlers.js"
 import {
   configExists,
   createConfigFromDefault,
@@ -506,10 +510,11 @@ export async function handleBuild(argv) {
 }
 
 /**
- * Handles `npx quartz update`
+ * Handles `npx quartz upgrade`
- * @param {*} argv arguments for `update`
+ * Upgrades the Quartz framework itself by pulling latest changes from upstream.
+ * @param {*} argv arguments for `upgrade`
  */
-export async function handleUpdate(argv) {
+export async function handleUpgrade(argv) {
   const contentFolder = resolveContentPath(argv.directory)
   console.log(`\n${styleText(["bgGreen", "black"], ` Quartz v${version} `)} \n`)
   console.log("Backing up your content")
@@ -528,6 +533,16 @@ export async function handleUpdate(argv) {
   }
 
   await popContentFolder(contentFolder)
+
+  // Read the new version after pulling
+  const newPkg = JSON.parse(fs.readFileSync("./package.json").toString())
+  const newVersion = newPkg.version
+  if (newVersion !== version) {
+    console.log(styleText("cyan", `Upgraded Quartz: v${version} → v${newVersion}`))
+  } else {
+    console.log(styleText("gray", `Quartz is already up to date (v${version})`))
+  }
+
   console.log("Ensuring dependencies are up to date")
 
   /*
@@ -535,7 +550,7 @@ export async function handleUpdate(argv) {
   as it will be unable to find `npm`. This is often the case on systems
   where `npm` is installed via a package manager.
 
-  This means `npx quartz update` will not actually update dependencies
+  This means `npx quartz upgrade` will not actually update dependencies
   on Windows, without a manual `npm i` from the caller.
 
   However, by spawning a shell, we are able to call `npm.cmd`.
@@ -563,6 +578,16 @@ export async function handleUpdate(argv) {
   console.log(styleText("green", "Done!"))
 }
 
+/**
+ * Handles `npx quartz update`
+ * Shortcut for `npx quartz plugin update` — updates all installed plugins.
+ * @param {*} argv arguments for `update`
+ */
+export async function handleUpdate(argv) {
+  console.log(`\n${styleText(["bgGreen", "black"], ` Quartz v${version} `)} \n`)
+  await handlePluginUpdate(argv.names)
+}
+
 /**
  * Handles `npx quartz restore`
  * @param {*} argv arguments for `restore`