quartz plugin

The plugin command is the heart of the Quartz v5 plugin management system. it allows you to install, configure, and update plugins directly from the command line.

All plugins are stored in the .quartz/plugins/ directory, and their versions are tracked in quartz.lock.json.

Subcommands

list

List all currently installed plugins and their versions.

npx quartz plugin list

add

Add a new plugin from a Git repository.

npx quartz plugin add github:username/repo

To install from a specific branch or ref, append #ref to the source:

npx quartz plugin add github:username/repo#my-branch
npx quartz plugin add git+https://github.com/username/repo.git#my-branch
npx quartz plugin add https://github.com/username/repo.git#my-branch

You can also add a plugin from a local directory. This is useful for local development or airgapped environments:

npx quartz plugin add ./path/to/my-plugin
npx quartz plugin add ../sibling-plugin
npx quartz plugin add /absolute/path/to/plugin

Local plugins are symlinked into .quartz/plugins/, so any changes you make to the source directory are reflected immediately without re-installing.

When a branch is specified, it is stored in the lockfile. All subsequent commands (install, prune) will respect that branch automatically. Use install --latest to fetch the latest commit from that branch.

remove

Remove an installed plugin.

npx quartz plugin remove plugin-name

install

Install plugins for your Quartz project. By default, this installs all plugins listed in your quartz.lock.json file.

npx quartz plugin install

Flags

• --from-config: Synchronize plugins with quartz.config.yaml instead of the lockfile. This will install missing plugins and prune orphaned ones.
• --latest: Fetch the latest version of plugins from their remote sources instead of using the version in the lockfile.
• --clean: Skip existing directories and perform a fresh installation.
• --dry-run: Preview the changes without actually installing or removing any files.

Positional Arguments

• [names..]: Optional list of specific plugin names to install or update.

# Update specific plugins to latest
npx quartz plugin install --latest plugin-a plugin-b
 
# Preview what would be installed from config
npx quartz plugin install --from-config --dry-run

enable / disable

Toggle a plugin’s status in your quartz.config.yaml without removing its files.

npx quartz plugin enable plugin-name
npx quartz plugin disable plugin-name

config

View or modify the configuration for a specific plugin.

# View config
npx quartz plugin config plugin-name
 
# Set a value
npx quartz plugin config plugin-name --set key=value

prune

Remove installed plugins that are no longer referenced in your quartz.config.yaml. This is useful for cleaning up after removing plugin entries from your configuration.

Note

Running plugin install --from-config also removes orphaned plugins as part of its synchronization. Use prune when you only want to clean up without installing anything new.

npx quartz plugin prune

Use --dry-run to preview which plugins would be removed without making changes:

npx quartz plugin prune --dry-run

Common Workflows

Adding and Enabling a Plugin

To add a new plugin and start using it:

1. Add the plugin: npx quartz plugin add github:quartz-community/example
2. Enable it: npx quartz plugin enable example

Updating Everything

To keep your plugins fresh:

npx quartz plugin install --latest

Managing Configuration

If you want to change a plugin setting without opening the YAML file:

npx quartz plugin config explorer --set useSavedState=true

Cleaning Up Unused Plugins

If you’ve removed plugins from your config and want to clean up leftover files:

npx quartz plugin prune --dry-run  # preview first
npx quartz plugin prune            # remove orphaned plugins

Setting Up from Config

When setting up on a new machine or in CI, install --from-config ensures your installed plugins match your config — installing missing plugins and removing any that are no longer referenced:

npx quartz plugin install --from-config

Testing with Branches

If a plugin author has a fix or feature on a separate branch, you can install it directly without waiting for a release to the default branch:

# Install from a feature branch
npx quartz plugin add github:username/repo#fix/some-bug
 
# Later, switch back to the default branch by re-adding without a ref
npx quartz plugin remove repo
npx quartz plugin add github:username/repo

The branch ref is tracked in quartz.lock.json, so install --latest will continue to follow the specified branch until the plugin is re-added without one.

Both prune and install --from-config will fall back to quartz.config.default.yaml if no quartz.config.yaml is present.

Local Plugin Development

For local plugin development or airgapped environments, you can add a plugin from a local directory:

npx quartz plugin add ./my-local-plugin

Local plugins are symlinked into .quartz/plugins/, so changes reflect immediately. When you run install --latest, local plugins are rebuilt (npm install + npm run build) without any git operations. The install --latest --dry-run command will show local plugins with a “local” status instead of checking for remote updates.

To switch a local plugin back to a git source:

npx quartz plugin remove my-local-plugin
npx quartz plugin add github:username/my-local-plugin

Subdirectory (Monorepo) Plugins

Some plugins live in a subdirectory of a larger repository rather than at the root. For these, you can specify the plugin source as an object in quartz.config.yaml with a subdir field:

quartz.config.yaml

plugins:
  - source:
      repo: "https://github.com/username/monorepo.git"
      subdir: plugin
    enabled: true

This tells Quartz to clone the full repository but install only the contents of the specified subdirectory.

You can combine subdir with ref to pin a branch or tag, and name to override the plugin directory name:

quartz.config.yaml

plugins:
  - source:
      repo: "https://github.com/username/monorepo.git"
      subdir: packages/my-plugin
      ref: v2.0
      name: my-plugin
    enabled: true

See Advanced Source Options for the full reference on object source fields.

Note

The plugin add CLI command works with string sources. To use the object source format with subdir, edit quartz.config.yaml directly, then run npx quartz plugin install --from-config to install it.

Migration from Deprecated Commands

Old command	New equivalent
npx quartz plugin restore	npx quartz plugin install --clean
npx quartz plugin update	npx quartz plugin install --latest
npx quartz plugin update my-plugin	npx quartz plugin install --latest my-plugin
npx quartz plugin check	npx quartz plugin install --latest --dry-run
npx quartz plugin resolve	npx quartz plugin install --from-config
npx quartz plugin resolve --dry-run	npx quartz plugin install --from-config --dry-run
npx quartz update	npx quartz plugin install --latest

The old commands still work as hidden aliases but will print a deprecation warning.

Plugin Status

Running the plugin command without any subcommand shows a status dashboard of all installed plugins, including whether updates are available:

npx quartz plugin

This displays each plugin with its source, commit, enabled/disabled status, and checks for available updates in parallel. For the full interactive management interface, use npx quartz tui instead.