CLI Commands

PicGo can be used directly from the command line. After installing picgo globally, run picgo -h to see all available commands:

bash

$ picgo -h

  Usage: picgo [options] [command]

  Options:

    -v, --version                 output the version number
    -d, --debug                   debug mode
    -s, --silent                  silent mode
    -c, --config <path>           set config path
    -h, --help                    output usage information

  Commands:

    install|add [options] <plugins...>   install picgo plugin
    uninstall|rm <plugins...>            uninstall picgo plugin
    update [options] <plugins...>        update picgo plugin
    set <module> [name] [configName]     configure config of picgo modules
    config [command]                     manage picgo config
    upload|u [input...]                  upload, go go go
    use [module] [name] [configName]     use modules of picgo
    uploader [command]                   manage uploader configurations
    login [token]                        login to picgo cloud (cloud.picgo.app)
    logout                               logout from picgo cloud (cloud.picgo.app)
    server [options]                     run PicGo as a standalone server
    i18n [lang]                          change picgo language
    help [command]                       display help for command

WARNING

Starting from PicGo-Core v1.7.0, PicGo no longer bundles the legacy picgo init command. Use the standalone picgo-init command instead (see picgo-init section below).

Tip

Options wrapped in <> are required, and options wrapped in [] are optional. Some commands have aliases—for example, picgo upload can be shortened to picgo u.

The CLI is built with commander.js and inquirer.js. Below is a walkthrough of the commands and how to use them.

use

Select a PicGo module. There are three kinds of modules: 1) transformer 2) uploader 3) plugins

bash

$ picgo use -h

  Usage: use [module] [name] [configName]

  use a module (uploader/transformer/plugin) of picgo

PicGo ships with the following built-ins:

transformer:
- path
- base64
uploader:
- smms -> SM.MS (S.EE)
- tcyun -> Tencent Cloud COS
- upyun -> UpYun
- aliyun -> Alibaba Cloud OSS
- qiniu -> Qiniu Cloud
- imgur -> Imgur
- github -> GitHub

Tip

In most CLI workflows, you only need to select path as the PicGo transformer.

Use picgo use or picgo use uploader|transformer|plugins to pick the module you want. This opens an interactive prompt:

bash

$ picgo use
? Use an uploader (Use arrow keys)
  smms
❯ tcyun
  weibo
  github
  qiniu
  imgur
  aliyun
(Move up and down to reveal more choices)

Starting from PicGo-Core v1.8.0, uploaders support multiple named configs. If an uploader has multiple configs, the interactive flow will ask you to choose one. You can also specify it directly:

bash

picgo use uploader <type> <configName>

configName is matched case-insensitively.

After you choose, PicGo will upload using the selected module. Some modules need configuration before you can use them (for example, tokens/keys for an image host). In that case, use set (described below) to configure the module.

uploader 1.8.0+

Manage uploader configurations (multi-config).

picgo uploader opens an interactive prompt (list/rename/copy/delete).
picgo uploader list [type] lists configs (marks current uploader and default config).
picgo uploader rename <type> <oldName> <newName>
picgo uploader copy <type> <configName> <newConfigName> (does not switch current uploader)
picgo uploader rm <type> <configName>

Config names are matched case-insensitively.

Examples:

bash

picgo uploader list
picgo uploader list github
picgo uploader rename github Work Personal
picgo uploader copy github Work Staging
picgo uploader rm github Staging

set

Configure module settings. There are three kinds of modules: 1) transformer 2) uploader 3) plugins

bash

$ picgo set -h

  Usage: set [options] <module> [name] [configName]

  configure config of picgo modules (uploader/transformer/plugin)

  Options:

    -h, --help  output usage information

Tip

Most of the time you only need to configure an uploader. You can run picgo set uploader (or picgo set uploader <type> [configName]) to jump straight into the interactive prompt.

Starting from PicGo-Core v1.8.0, set uploader works with uploader multi-config: you can choose an existing config (by name) or create a new one, and the saved config becomes the active config for that uploader.

For the detailed configuration fields of built-in uploaders (image hosts), refer to PicGo’s configuration wiki。

If an uploader/transformer/plugin has no configurable options, PicGo will still report success—this is expected.

bash

$ picgo set transformer path
[PicGo SUCCESS]: Configure config successfully!

bash

picgo login [token]

If token is provided, PicGo verifies it via Cloud API and saves it on success.
If token is omitted, PicGo first tries the existing token; if invalid, it starts a browser-based login flow.
The browser flow starts a local callback server and opens the login URL at https://cloud.picgo.app. If the browser cannot be opened automatically, PicGo prints the URL so you can open it manually.

logout 2.0+

Log out from PicGo Cloud (https://cloud.picgo.app) and clear the local token.

bash

picgo logout

Clears settings.picgoCloud.token locally.

config 2.0+

Manage config-related operations.

config sync

bash

picgo config sync [--encrypt <auto|sse|e2ee>]

Syncs local config with PicGo Cloud using a 3-way merge (snapshot + local + remote).
On the first sync (or when remote is missing), local config is pushed to cloud and a snapshot baseline is created.
On conflict, PicGo prints a diff tree and prompts Use Local, Use Remote, or Abort. Local config is not overwritten until you choose a resolution.
settings.picgoCloud.token and settings.picgoCloud.encryptionMethod are treated as local-only values and are not overwritten by cloud data.
Requires a valid Cloud token. Run picgo login (cloud.picgo.app) first.

Encryption method flags

--encrypt <method>: validate <method> as one of auto, sse, e2ee, then persist settings.picgoCloud.encryptionMethod = <method> before sync starts.
Methods: auto follows the last encryption method stored in cloud config, sse uses server-side encryption, and e2ee enables end-to-end encryption with a PIN.
If <method> is invalid or missing, PicGo fails with: Invalid configuration: settings.picgoCloud.encryptionMethod must be one of 'auto', 'sse', 'e2ee'. Found: "<value>".
Without flags, PicGo follows local preference (settings.picgoCloud.encryptionMethod); if missing, it defaults to auto without persisting it.
When E2EE is used, PicGo prompts for a PIN (enter twice; retry up to 3 times on mismatch). If the PIN is incorrect during decryption, PicGo retries up to 3 times before failing.
For a deeper explanation of the encryption modes, see PicGo Blog.

server 2.0+

Run PicGo as a standalone local server.

bash

picgo server [options]

Options:

-p, --port <n>: server port (default 36677).
-h, --host <s>: server host (default 127.0.0.1).
-i, --ignore-existing-external-server: ignore an existing PicGo server on the same address.
--secret <s>: enable server authentication with a shared secret.

When the port is already in use, PicGo checks whether an existing PicGo server is running on that address. If so, it reuses the port (unless --ignore-existing-external-server is set). Otherwise it increments the port and retries.

Built-in endpoints

POST /heartbeat → { success: true, result: "alive" }
POST /upload
- Empty body, {}, or { "list": [] } uploads from clipboard.
- { "list": ["path1", "path2"] } uploads the provided file paths.
- Invalid JSON returns HTTP 400.
- multipart/form-data with field files uploads file(s) and cleans up temp files under baseDir.

Authentication (optional)

Authentication is enabled when a non-empty secret is resolved (priority: --secret → PICGO_SERVER_SECRET → settings.server.secret). The secret is trimmed; whitespace-only values disable authentication.

Protected routes: POST /upload and all plugin-registered routes (including mounted routers).
Credential priority: Authorization: Bearer <token> (case-insensitive) → X-PicGo-Secret → ?secret=<token>.
- If Authorization is present, PicGo does not fall back to lower-priority sources.
- Using ?secret= is supported but discouraged; PicGo logs a warning once per process.
Unauthorized responses return HTTP 401 with { success: false, message: "Unauthorized" }.
PicGo logs whether authentication is enabled at startup and logs unauthorized attempts with the client IP (preferring X-Forwarded-For).

Example:

bash

picgo server --secret mytoken
curl -H "Authorization: Bearer mytoken" -H "Content-Type: application/json" -d '{"list":[]}' http://127.0.0.1:36677/upload

upload|u

Upload images to an image host. Typically you upload local files (multiple files separated by spaces). You can also upload the first image from your clipboard.

Tip

Before uploading, make sure you’ve selected the right module with use and configured the target image host with set.

bash

$ picgo u ./Test-example.jpg ./test-qiniu.png
[PicGo INFO]: Before transform
[PicGo INFO]: Transforming...
[PicGo INFO]: Before upload
[PicGo INFO]: Uploading...
[PicGo SUCCESS]:
https://i.loli.net/2018/09/06/5b9134645b9df.jpg
https://i.loli.net/2018/09/06/5b9134651af34.png

If you don’t provide any input files, PicGo uploads the first image from your clipboard (due to cross-platform limitations it will be converted to PNG). This is especially handy for uploading screenshots.

bash

$ picgo u
[PicGo INFO]: Before transform
[PicGo INFO]: Transforming...
[PicGo INFO]: Before upload
[PicGo INFO]: Uploading...
[PicGo SUCCESS]:
https://i.loli.net/2018/09/06/5b9134645b9df.jpg

install|add

Install PicGo plugins from npm. Plugin packages are named with the picgo-plugin- prefix. When installing/uninstalling/updating, you only need to provide the short name (without the picgo-plugin- prefix). You can install multiple plugins by separating them with spaces.

Tip

PicGo installs plugins into the directory where your config file lives. With the default config under ~/.picgo/, plugins will be installed into ~/.picgo/node_modules/.

You can search for PicGo plugins on npm. Plugins follow the naming pattern picgo-plugin-[name], and can be installed with:

bash

picgo install [name]

After installing, you can use picgo ch plugins to enable or disable the plugin.

uninstall|rm

Uninstall a PicGo plugin. PicGo will throw an error if the plugin is not installed.

bash

picgo uninstall [name]

update

Update an installed PicGo plugin. PicGo will throw an error if the plugin is not installed.

bash

picgo update [name]

i18n

Switch PicGo’s UI language. Supported languages:

zh-CN (default)
zh-TW
en

Example:

bash

picgo i18n en

-v, --version

Run picgo -v or picgo --version to print the current PicGo version.

-d, --debug

Add -d or --debug to any valid command to enter debug mode. PicGo will print more detailed error information, including where the error occurred.

-c, --config

Add -c <path> to specify the PicGo config file path. The default config file is ~/.picgo/config.json.

Tip

PicGo loads plugins from the node_modules directory next to the config file.

-s, --silent

Add -s or --silent to any valid command to enter silent mode. PicGo will output nothing except error messages.

picgo-init

Download and generate a PicGo plugin development template.

Starting from PicGo-Core v1.7.0, this is provided by the standalone picgo-init command. See PicGo/PicGo-Init for installation and usage.

bash

$ picgo-init -h

Usage: picgo-init <template> [project]

create picgo plugin's development templates

Options:
  --offline   use cached template
  --debug     debug mode
  -h, --help  display help for command

Examples:

  # create a new project with an official template
  $ picgo-init plugin my-project

  # create a new project straight from a github template
  $ picgo-init username/repo my-project

Similar to vue-cli’s init, PicGo provides official templates. When running picgo-init, you can use plugin as the template name. Internally, if the template is not in username/repo form, PicGo automatically prefixes it with PicGo/picgo-template-.

This command helps you bootstrap a PicGo plugin quickly. For details, see Plugin Development.

Overview

How does it work?

Getting Started

Configuration

Default config file

picBed

settings

CLI Commands

config

Use in Node.js

Initialization

PicGo Cloud

Event listeners

Lifecycle plugins

Loading third-party plugins

CLI Commands

use

uploader 1.8.0+

set

logout 2.0+

config 2.0+

config sync

Encryption method flags

server 2.0+

Built-in endpoints

Authentication (optional)

upload|u

install|add

uninstall|rm

update

i18n

-v, --version

-d, --debug

-c, --config

-s, --silent

picgo-init

How does it work?

Default config file

picBed

settings

config

Initialization

PicGo Cloud

Event listeners

Lifecycle plugins

Loading third-party plugins

CLI Commands ​

use ​

uploader 1.8.0+ ​

set ​

login 2.0+ ​

logout 2.0+ ​

config 2.0+ ​

config sync ​

Encryption method flags ​

server 2.0+ ​

Built-in endpoints ​

Authentication (optional) ​

upload|u ​

install|add ​

uninstall|rm ​

update ​

i18n ​

-v, --version ​

-d, --debug ​

-c, --config ​

-s, --silent ​

picgo-init ​

CLI Commands

use

uploader 1.8.0+

set

login 2.0+

logout 2.0+

config 2.0+

config sync

Encryption method flags

server 2.0+

Built-in endpoints

Authentication (optional)

upload|u

install|add

uninstall|rm

update

i18n

-v, --version

-d, --debug

-c, --config

-s, --silent

picgo-init