CLI Reference

cli:

• purpose: create projects, build sites, sync GitHub, manage plugins
• invocation: npx quartz

Quick Reference

Command	Description	Example
create	Initialize a new Quartz project with template selection	npx quartz create
build	Generate static HTML files	npx quartz build
sync	Sync content with GitHub	npx quartz sync
upgrade	Upgrade Quartz to the latest version (alias: update)	npx quartz upgrade
plugin	Manage Quartz plugins (install, add, remove, etc.)	npx quartz plugin list
tui	Launch the interactive plugin manager	npx quartz tui

Commands

commands:

• create: initialize a project with templates (default, obsidian, ttrpg, blog) and baseUrl
• build: build static HTML; optionally serve and watch
• sync: pull, commit, push via GitHub
• upgrade: upgrade Quartz framework; alias: npx quartz update
• restore: restore content from local cache
• plugin: install, add, remove, prune, configure plugins; supports lockfile/config sync, updates, checks
• tui: manage plugins and layout via terminal UI

Global Flags

global_flags:

• accepted_by: every Quartz command

Flag	Shorthand	Description	Default
--directory	-d	The directory containing your Quartz project	content
--verbose	-v	Enable detailed logging for debugging	false
--concurrency	-c	Max parallel workers for operations that run in parallel (e.g. build, plugin install, plugin add)	CPU core count

notes:

• commands without parallel work accept -c as a no-op
• examples: build, plugin

Help and Versioning

help:

• command flags: use --help

npx quartz --help
npx quartz build --help

version:

• current Quartz version: use --version

npx quartz --version

create

create:

• purpose: initialize a Quartz project
• configures:
  • content folder
  • template
  • baseUrl
  • Markdown handling strategy
  • internal link resolution

Flags

Flag	Shorthand	Description
--template	-t	Configuration template (default, obsidian, ttrpg, or blog)
--directory	-d	The directory where Quartz will be initialized
--source	-s	The source directory of your Markdown files
--strategy	-X	How to handle the source files (new, copy, or symlink)
--links	-l	How to resolve internal links (absolute, shortest, or relative)
--baseUrl	-b	Base URL for your site (e.g. mysite.github.io/quartz)
--verbose	-v	Enable detailed logging

Templates

template_behavior:

• quartz create: prompts for a configuration template
• selected template:
  • overwrites quartz.config.yaml
  • triggers plugin resolution
  • installs required plugins
  • removes unreferenced plugins

templates:

• default: clean setup; sensible defaults; best for new projects
• obsidian:
  • optimized for Obsidian vaults
  • enables Obsidian Flavored Markdown support: wikilinks, callouts, Mermaid diagrams
  • sets link resolution to shortest
  • skips link-resolution prompt
• ttrpg:
  • extends obsidian
  • adds Leaflet bases plugin
  • adds ITS Theme variant its-theme.ttrpg-dnd
  • targets D&D and TTRPG wikis
  • skips link-resolution prompt
• blog:
  • enables recent notes
  • shows 5 most recent posts with tags
  • enables comments via giscus
  • requires replacing TODO: placeholders in quartz.config.yaml with giscus repository details

Base URL

base_url:

• definition: deployed site URL, e.g. mysite.github.io/quartz
• omit: protocol, e.g. https://
• behavior:
  • protocol strips automatically if included
  • trailing slashes strip automatically
• reference: configuration

Strategies

strategies:

• new: create fresh empty content folder; use for new projects
• copy: copy all source files into Quartz content folder; safest for existing vaults; original files unchanged
• symlink: link Quartz content folder to source directory; source changes reflect immediately in Quartz

Link Resolution

link_resolution:

• purpose: interpret internal Markdown links
• modes:
  • shortest: closest matching file name; Obsidian default
  • absolute: relative to content root
  • relative: relative to current file location

Note

create_template_defaults:

• obsidian and ttrpg: set link resolution to shortest; skip link-resolution prompt

Interactive Walkthrough

interactive_create:

• command: npx quartz create
• steps:
  • template: choose Default, Obsidian, TTRPG, or Blog
  • strategy: choose new, copy, or symlink
  • base URL: enter deployment URL
  • link resolution: choose link style; skipped for obsidian and ttrpg
  • finish:
    • create directory structure
    • create configuration
    • install template-referenced plugins

Example: Importing an Obsidian Vault

goal:

• link a Quartz project directly to an existing Obsidian vault

npx quartz create --template obsidian --strategy symlink --source ~/Documents/MyVault

effect:

• uses obsidian template with OFM and shortest link resolution
• reads vault at ~/Documents/MyVault
• uses symlinks so source changes sync immediately

Example: Setting Up a Blog

goal:

• create a blog with recent notes and comments

npx quartz create --template blog --strategy new --baseUrl myblog.github.io

after_setup:

• edit quartz.config.yaml
• replace giscus TODO: values in comments plugin config

build

build:

• purpose: transform Markdown into static HTML
• pipeline: configured plugins
• output: site directory

Flags

Flag	Shorthand	Description	Default
--directory	-d	The directory containing your Quartz project	Current directory
--verbose	-v	Enable detailed logging for debugging	false
--output	-o	The directory where the built site will be saved	public
--serve		Start a local development server	false
--watch		Rebuild the site when files change	false
--port		The port for the development server	8080
--wsPort		The port for the WebSocket hot-reload server	3001
--wsPublicPort		Public TLS port for remote WebSocket hot reload (browser connects here; reverse proxy forwards to --wsPort)	3002
--baseDir		Set a base directory for the site (e.g. for GitHub Pages)	/
--remoteDevHost		The hostname to use for the development server	localhost
--bundleInfo		Output a JSON file with bundle size information	false
--concurrency	-c	Number of worker threads to use for building	CPU core count

Examples

Basic Build

output:

• default: public

npx quartz build

Development Mode

development:

• starts local server
• watches for changes
• recommended preview mode while writing

npx quartz build --serve

Custom Output and Port

customization:

• output folder: dist
• development server port: 3000

npx quartz build --serve --output dist --port 3000

Performance Tuning

large_vaults:

• reduce concurrent workers to lower memory use

npx quartz build --concurrency 2

Serve vs Watch

serve_vs_watch:

• --serve:
  • starts local development server
  • implies --watch
  • recommended for local development
• --watch:
  • watches file changes
  • rebuilds automatically
  • does not start a server
  • useful for CI or custom serving

common_choice:

• use --serve

npx quartz build --serve

Development Server

development_server:

• enabled_by: --serve
• purpose: preview only
• not_for: production
• deployment_reference: hosting

Hot Reloading

hot_reload:

• --serve enables --watch
• WebSocket port: --wsPort
• browser refreshes after file changes

sync

sync:

• purpose: automate GitHub pull, commit, push
• audience: users avoiding manual Git commands

Flags

Flag	Shorthand	Description	Default
--directory	-d	The directory of your Quartz project	Current directory
--verbose	-v	Enable detailed logging	false
--commit		Whether to commit changes	true
--no-commit		Skip committing changes	false
--message	-m	Custom commit message	update content
--push		Whether to push changes to remote	true
--no-push		Skip pushing changes	false
--pull		Whether to pull changes from remote	true
--no-pull		Skip pulling changes	false

Workflow

workflow:

• pull: fetch and merge remote GitHub changes
• add: stage new and modified project files
• commit: create commit
• push: send commit to GitHub

Common Workflows

Regular Sync

regular_sync:

• pulls, commits, pushes all changes

npx quartz sync

First Sync

first_sync:

• use after creating a repository with nothing pushed
• skip pull

npx quartz sync --no-pull

Custom Commit Message

custom_commit_message:

• set explicit message

npx quartz sync --message "add new notes about gardening"

Sync from Another Device

sync_from_another_device:

• pull latest changes
• do not commit or push local changes

npx quartz sync --no-push --no-commit

Troubleshooting

Git Buffer

git_buffer:

• symptom: Git fails with many changes
• fixes:
  • sync smaller batches
  • increase Git post buffer size

Autostash

autostash:

• internal command: git pull --rebase --autostash
• behavior:
  • temporarily hides unstaged changes
  • pulls remote changes
  • reapplies local changes
• conflicts: resolve manually with standard Git tools
• setup_reference: installation

upgrade

upgrade:

• purpose: upgrade Quartz framework to latest version via official repository

Usage

npx quartz upgrade

How it Works

upgrade_steps:

• back up content: cache content folder locally
• pull latest Quartz code: fetch and merge from upstream/v5
• show version changes: display transition, e.g. v5.0.0 → v5.1.0, or up-to-date status
• update dependencies: run npm install
• restore plugins: reinstall from quartz.lock.json
• check plugin compatibility: verify installed plugins against new Quartz version

Handling Conflicts

conflicts:

• cause: local edits overlap upstream Quartz changes
• lockfile handling:
  • backs up quartz.lock.json before pulling
  • restores it after pulling
  • avoids common upgrade conflicts
• other files:
  • Git marks conflicting sections
  • open files and choose changes
  • commit resolved files

Recovery

recovery:

• use restore if upgrade fails or leaves project unusable

Flags

flags:

• supports: global flags (--directory, --verbose)

See Also

see_also:

• quartz plugin install —latest: update installed plugins
• Upgrading Quartz: detailed upgrading guide
• quartz restore: recover content from cache

restore

restore:

• purpose: recover content folder from local cache
• scope:
  • restores Markdown files
  • does not restore plugins
  • does not restore configuration
• plugin_restore: use npx quartz plugin install

When to Use

use_restore_when:

• quartz upgrade failed and corrupted content
• content files were deleted accidentally
• merge conflicts became complex enough to abandon

How it Works

mechanics:

• Quartz maintains hidden content-folder cache
• selected commands ensure Markdown backups exist
• restore copies cached files into main content directory

npx quartz restore

Example Workflow

failed_update_recovery:

• restore: run npx quartz restore
• clean: use Git to reset broken code files
• retry: run update again or apply needed changes manually

plugin

plugin:

• purpose: install, configure, update plugins from CLI
• storage: .quartz/plugins/
• version_tracking: quartz.lock.json

Subcommands

list

list:

• shows installed plugins and versions

npx quartz plugin list

add

add:

• adds plugin from Git repository

npx quartz plugin add github:username/repo

refs:

• append #ref for branch, tag, or commit

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

local_sources:

• add plugin from local directory
• useful for local development and 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_behavior:

• symlinks into .quartz/plugins/
• source changes reflect immediately
• no reinstall required

branch_behavior:

• specified branch stores in lockfile
• later install and prune respect branch
• install --latest fetches latest commit from that branch

Tip

concurrency:

• plugin add accepts --concurrency / -c
• limits simultaneous remote clone/build jobs
• useful when adding several plugins on low-end hardware
• same flag documented under install

remove

remove:

• removes installed plugin

npx quartz plugin remove plugin-name

install

install:

• installs project plugins
• default source: quartz.lock.json

npx quartz plugin install

Flags

flags:

• --from-config: sync plugins with quartz.config.yaml; install missing plugins; prune orphaned plugins
• --latest: fetch latest plugin versions from remotes instead of lockfile versions
• --clean: skip existing directories and perform fresh installation
• --dry-run: preview changes without installing or removing files
• --concurrency, -c:
  • max plugins cloned, fetched, built in parallel
  • default: CPU core count
  • use -c 1 or -c 2 on memory/CPU-constrained machines when default parallelism fails, OOMs, or hangs
  • reference: Installing on low-end hardware

Positional Arguments

positional_arguments:

• [names..]: optional 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

enable_disable:

• toggles plugin status in quartz.config.yaml
• keeps plugin files installed

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

config

config:

• views or modifies specific plugin configuration

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

prune

prune:

• removes installed plugins no longer referenced in quartz.config.yaml
• useful after removing plugin entries from config

Note

synchronization:

• plugin install --from-config also removes orphaned plugins
• use prune when cleaning only, without installing anything new

npx quartz plugin prune

dry_run:

• preview removals without changes

npx quartz plugin prune --dry-run

Common Workflows

Adding and Enabling a Plugin

add_and_enable:

• add: npx quartz plugin add github:quartz-community/example
• enable: npx quartz plugin enable example

Updating Everything

update_all:

• fetch latest plugin versions

npx quartz plugin install --latest

Installing on low-end hardware

low_end_hardware:

• default behavior:
  • plugin install and plugin add clone, fetch, and build across all CPU cores
  • each worker may run npm install / npm run build
• risk:
  • RAM exhaustion
  • CPU overload
  • hangs
• affected environments:
  • low-end laptops
  • Raspberry Pi
  • small VPS instances
  • restrictive CI runners

Note

prebuilt_plugins:

• most community plugins ship with dist/
• Quartz skips install/build when dist/ exists
• faster and lighter
• concurrency tuning mainly affects development plugins or plugins without prebuilt distribution

failure_response:

• symptoms: failure, hang, OOM
• fix: lower concurrency with --concurrency / -c

## Install one plugin at a time (safest, slowest)
npx quartz plugin install --latest -c 1
 
## Two at a time — usually a good balance on 4 GB machines
npx quartz plugin install --latest --concurrency 2

parallel_subcommands:

• same flag applies to plugin add and plugin subcommands that run parallel work

npx quartz plugin add github:quartz-community/some-plugin -c 1

Managing Configuration

configuration_edit:

• change plugin setting without opening YAML

npx quartz plugin config explorer --set useSavedState=true

Cleaning Up Unused Plugins

cleanup:

• use after removing plugins from config
• preview before pruning

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

Setting Up from Config

setup_from_config:

• use on new machines or CI
• install --from-config matches installed plugins to config
• installs missing plugins
• removes unreferenced plugins

npx quartz plugin install --from-config

Testing with Branches

branches:

• install unreleased fixes/features directly from branch
• re-add without ref to return to 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

branch_tracking:

• quartz.lock.json stores branch ref
• install --latest follows branch until plugin is re-added without a ref

config_fallback:

• prune and install --from-config fall back to quartz.config.default.yaml when quartz.config.yaml is absent

Local Plugin Development

local_development:

• add plugin from local directory
• useful for development and airgapped environments

npx quartz plugin add ./my-local-plugin

local_plugin_behavior:

• symlinks into .quartz/plugins/
• source changes reflect immediately
• install --latest rebuilds local plugins with npm install + npm run build
• no Git operations

Note

local_symlink_builds:

• local symlinked plugins usually use build-on-install fallback
• reason: dist/ is usually gitignored during development

dry_run_local:

• install --latest --dry-run shows local plugins with local status
• skips remote update checks

switch_local_to_git:

• remove local plugin
• add Git source

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

Subdirectory (Monorepo) Plugins

monorepo_plugins:

• use when plugin lives in repository subdirectory
• specify object source in quartz.config.yaml with subdir

quartz.config.yaml

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

behavior:

• clones full repository
• installs only specified subdirectory

advanced_source_options:

• combine subdir with ref to pin branch/tag
• use name to override 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

reference:

• Advanced Source Options

Note

cli_limit:

• plugin add accepts string sources
• for object source format with subdir, edit quartz.config.yaml
• then run npx quartz plugin install --from-config

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

deprecated_commands:

• hidden aliases still work
• emit deprecation warning

Plugin Status

plugin_status:

• running without subcommand shows installed-plugin dashboard
• includes:
  • source
  • commit
  • enabled/disabled status
  • update availability
• checks updates in parallel
• interactive alternative: npx quartz tui

npx quartz plugin

tui

tui:

• purpose: interactive terminal UI for Quartz project management
• manages:
  • plugins
  • site layout
  • general settings

Prerequisites

requirements:

• Bun:
  • required runtime
  • install docs: bun.sh
• TUI Plugin:
  • must be installed in the Quartz project

Installation

install_tui_plugin:

• add TUI plugin

npx quartz plugin add github:quartz-community/tui

Interface Panels

panels:

• count: 3
• navigation: switch between panels

Plugins Panel

plugins_panel:

• browse available and installed plugins
• enable or disable plugins with one keystroke
• configure plugin-specific settings
• install community plugins
• remove installed plugins

Layout Panel

layout_panel:

• defines component placement
• move components between sections, e.g. left, right, beforeBody
• reorder components inside a section
• set component priorities

Settings Panel

settings_panel:

• edits quartz.config.yaml
• configurable:
  • pageTitle
  • theme colors and fonts
  • analytics configuration
  • deployment settings

Navigation

keys:

• arrow keys: move between items and panels
• Enter: select item or confirm change
• Esc: go back or cancel action
• Tab: cycle interface elements

Important Note

tui_writes:

• changes write directly to quartz.config.yaml
• use a clean Git state before opening TUI
• review and undo changes through Git

cli_plugin_management:

• reference: quartz plugin