How to Configure Watermark Settings via the PicList-Core CLI: A Complete Guide

You configure watermark settings in PicList-Core by running picgo set buildin watermark, which launches an interactive prompt sequence defined in the watermark plugin and saves your choices to the buildIn.watermark key in your PicGo configuration file.

PicList-Core extends the PicGo ecosystem with a built-in watermark processor that integrates directly into the CLI workflow. According to the kuingsmile/piclist-core source code, all watermark configuration is managed through the buildIn.watermark configuration namespace, accessible via both interactive and direct command-line interfaces.

Architecture of the Watermark Configuration System

The watermark configuration flow involves three core components working together when you run picgo set buildin watermark.

In src/plugins/commander/setting.ts, the handleBuildinModule function (lines 9-15) routes CLI commands to built-in modules. It looks up the BUILDIN_MODULES map to find the watermark entry, then invokes the plugin's configuration handler.

The src/plugins/beforetransformer/watermark.ts file exports a config(ctx) function that builds the interactive prompt list. This function retrieves existing settings via ctx.getConfig<IBuildInWaterMarkOptions>('buildIn.watermark') and constructs a series of confirm, list, and input prompts based on the IBuildInWaterMarkOptions interface defined in src/types/index.ts (lines 673-699).

After you answer the prompts, the handleConfig helper saves the result using ctx.saveConfig({ 'buildIn.watermark': answer }), persisting the configuration to ~/.picgo/config.json or the path specified by PICGO_CONFIG_PATH.

Available Watermark Configuration Options

The IBuildInWaterMarkOptions interface in src/types/index.ts defines the following configurable fields with their default values:

• isAddWatermark (boolean, default: false) – Master toggle to enable or disable watermarking.
• watermarkType ('text' | 'image', default: 'text') – Choose between textual or image-based watermarks.
• isFullScreenWatermark (boolean, default: false) – Stretch the watermark to cover the entire image.
• watermarkDegree (number, default: 0) – Rotation angle in degrees.
• watermarkText (string, default: '') – Text content when using text watermarks.
• watermarkFontPath (string, default: '') – Absolute path to a TTF or OTF font file.
• watermarkScaleRatio (number 0-1, default: 0.15) – Relative size of the watermark compared to the source image.
• watermarkColor (string CSS rgba, default: 'rgba(204, 204, 204, 0.45)') – Color for text watermarks.
• watermarkImagePath (string, default: '') – Path to an image file when watermarkType is set to 'image'.
• watermarkImageOpacity (number 0-255, default: 255) – Opacity level for image watermarks.
• watermarkPosition (string, default: 'southeast') – Anchor position (e.g., north, northeast, center, southeast).

Configuring Watermark Settings via the CLI

You can configure watermark settings through two methods: an interactive wizard or direct key-value assignment.

Interactive Configuration

Run the built-in configuration command to launch the interactive UI:

picgo set buildin watermark

The CLI will present a sequence of prompts defined in watermark.ts (lines 7-73):

? Add watermark? (y/N)
? Watermark type (text, image)
? Full-screen watermark? (y/N)
? Watermark degree (0)
? Watermark text ()
? Watermark font path ()
? Watermark scale ratio (0.15)
? Watermark color (rgba(204, 204, 204, 0.45))
? Watermark image path ()
? Watermark image opacity (255)
? Watermark position (north, northeast, southeast, ...)

Your responses are validated against the IBuildInWaterMarkOptions schema and saved immediately to your configuration file.

Non-Interactive Configuration

For automation or scripting, set individual properties directly without prompts:

# Enable watermark globally

picgo set buildIn.watermark.isAddWatermark true

# Configure an image watermark

picgo set buildIn.watermark.watermarkType image
picgo set buildIn.watermark.watermarkImagePath /path/to/logo.png
picgo set buildIn.watermark.watermarkImageOpacity 180
picgo set buildIn.watermark.watermarkPosition southeast

These commands bypass the interactive UI and write values directly to the buildIn.watermark object in your config file.

Verifying Your Configuration

To confirm your watermark settings were saved correctly, retrieve the current configuration:

picgo get buildIn.watermark

This outputs the JSON object stored in your config file, allowing you to verify values like watermarkScaleRatio and watermarkPosition before processing images.

Summary

• Entry command: Use picgo set buildin watermark to access the interactive configuration wizard defined in src/plugins/beforetransformer/watermark.ts.
• Storage location: All settings persist under the buildIn.watermark key in your PicGo configuration file (default: ~/.picgo/config.json).
• Type safety: The IBuildInWaterMarkOptions interface in src/types/index.ts defines the complete schema including text, image, positioning, and opacity options.
• Dual interface: Configure via interactive prompts for ease, or use direct picgo set buildIn.watermark.<key> <value> commands for automation.
• Integration: The upload pipeline reads these settings via src/utils/common.ts to apply watermarks during image processing.

Frequently Asked Questions

Where does PicList-Core store watermark configuration?

PicList-Core saves watermark settings under the buildIn.watermark key in your global PicGo configuration file, typically located at ~/.picgo/config.json. You can override this location by setting the PICGO_CONFIG_PATH environment variable.

Can I configure watermarks without using the interactive prompts?

Yes. While picgo set buildin watermark launches an interactive UI, you can set specific values directly using the syntax picgo set buildIn.watermark.<option> <value>. For example, picgo set buildIn.watermark.isAddWatermark true enables watermarks immediately without prompts.

What image formats are supported for image watermarks?

The watermark processor accepts standard image formats via the watermarkImagePath field. You specify the absolute path to your logo or watermark image file, and the system applies it using the opacity and positioning settings defined in IBuildInWaterMarkOptions.

How do I change the font for text watermarks?

Set the watermarkFontPath option to the absolute path of your TTF or OTF font file. In interactive mode, the CLI prompts you for this path; in non-interactive mode, use picgo set buildIn.watermark.watermarkFontPath /path/to/font.ttf.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}