docs: updated cli commands
This commit is contained in:
saberzero1
@@ -42,7 +42,7 @@ 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`, `update`, `restore`, `check`, `resolve`) will respect that branch automatically.
|
||||
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
|
||||
|
||||
@@ -54,27 +54,29 @@ npx quartz plugin remove plugin-name
|
||||
|
||||
### install
|
||||
|
||||
Install all plugins listed in your `quartz.lock.json` file. This is useful when setting up the project on a new machine.
|
||||
Install plugins for your Quartz project. By default, this installs all plugins listed in your `quartz.lock.json` file.
|
||||
|
||||
```shell
|
||||
npx quartz plugin install
|
||||
```
|
||||
|
||||
### update
|
||||
#### Flags
|
||||
|
||||
Update specific plugins or all plugins to their latest versions.
|
||||
- `--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.
|
||||
|
||||
```shell
|
||||
npx quartz plugin update plugin-name
|
||||
npx quartz plugin update # updates all
|
||||
```
|
||||
# Update specific plugins to latest
|
||||
npx quartz plugin install --latest plugin-a plugin-b
|
||||
|
||||
### restore
|
||||
|
||||
Restore plugins to the exact versions specified in the lockfile. Unlike `install`, this will downgrade plugins if the lockfile specifies an older version. This is recommended for CI/CD environments.
|
||||
|
||||
```shell
|
||||
npx quartz plugin restore
|
||||
# Preview what would be installed from config
|
||||
npx quartz plugin install --from-config --dry-run
|
||||
```
|
||||
|
||||
### enable / disable
|
||||
@@ -98,20 +100,12 @@ npx quartz plugin config plugin-name
|
||||
npx quartz plugin config plugin-name --set key=value
|
||||
```
|
||||
|
||||
### check
|
||||
|
||||
Check if any of your installed plugins have updates available.
|
||||
|
||||
```shell
|
||||
npx quartz plugin check
|
||||
```
|
||||
|
||||
### 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]
|
||||
> The `resolve` command also removes orphaned plugins as part of its synchronization. Use `prune` when you only want to clean up without installing anything new.
|
||||
> 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.
|
||||
|
||||
```shell
|
||||
npx quartz plugin prune
|
||||
@@ -123,20 +117,6 @@ Use `--dry-run` to preview which plugins would be removed without making changes
|
||||
npx quartz plugin prune --dry-run
|
||||
```
|
||||
|
||||
### resolve
|
||||
|
||||
Synchronize your installed plugins with your `quartz.config.yaml`. This installs plugins that are in your config but missing from the lockfile, and removes plugins that are in the lockfile but no longer referenced in your config.
|
||||
|
||||
```shell
|
||||
npx quartz plugin resolve
|
||||
```
|
||||
|
||||
Use `--dry-run` to preview which plugins would be installed without making changes:
|
||||
|
||||
```shell
|
||||
npx quartz plugin resolve --dry-run
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Adding and Enabling a Plugin
|
||||
@@ -151,7 +131,7 @@ To add a new plugin and start using it:
|
||||
To keep your plugins fresh:
|
||||
|
||||
```shell
|
||||
npx quartz plugin update
|
||||
npx quartz plugin install --latest
|
||||
```
|
||||
|
||||
### Managing Configuration
|
||||
@@ -173,10 +153,10 @@ npx quartz plugin prune # remove orphaned plugins
|
||||
|
||||
### Setting Up from Config
|
||||
|
||||
When setting up on a new machine or in CI, resolve ensures your installed plugins match your config — installing missing plugins and removing any that are no longer referenced:
|
||||
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:
|
||||
|
||||
```shell
|
||||
npx quartz plugin resolve
|
||||
npx quartz plugin install --from-config
|
||||
```
|
||||
|
||||
### Testing with Branches
|
||||
@@ -192,9 +172,9 @@ npx quartz plugin remove repo
|
||||
npx quartz plugin add github:username/repo
|
||||
```
|
||||
|
||||
The branch ref is tracked in `quartz.lock.json`, so `update` and `check` will continue to follow the specified branch until the plugin is re-added without one.
|
||||
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 `resolve` will fall back to `quartz.config.default.yaml` if no `quartz.config.yaml` is present.
|
||||
Both `prune` and `install --from-config` will fall back to `quartz.config.default.yaml` if no `quartz.config.yaml` is present.
|
||||
|
||||
### Local Plugin Development
|
||||
|
||||
@@ -204,7 +184,7 @@ For local plugin development or airgapped environments, you can add a plugin fro
|
||||
npx quartz plugin add ./my-local-plugin
|
||||
```
|
||||
|
||||
Local plugins are symlinked into `.quartz/plugins/`, so changes reflect immediately. When you run `update`, local plugins are rebuilt (npm install + npm run build) without any git operations. The `check` command will show local plugins with a "local" status instead of checking for remote updates.
|
||||
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:
|
||||
|
||||
@@ -242,7 +222,21 @@ plugins:
|
||||
See [[configuration#Advanced Source Options|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 resolve` to install it.
|
||||
> 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.
|
||||
|
||||
## Interactive Mode
|
||||
|
||||
|
||||
Reference in New Issue
Block a user