CLI Commands

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

$ picgo -h

  Usage: picgo [options] [command]

  Options:

    -v, --version                 output the version number
    -d, --debug                   debug mode
    -s, --silent                  silent mode
    -p, --proxy <url>             set proxy for uploading
    -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
    get <module>                         inspect current module config
    login [token]                        login to picgo cloud (cloud.picgo.app)
    logout                               logout from picgo cloud (cloud.picgo.app)
    cloud                                picgo cloud commands
    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

$ 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:

$ 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:

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:

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

$ 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.

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

get 3.0+

Inspect the currently selected PicGo module configuration. Supports three sub-commands, all of which accept --format pretty|json (default pretty).

picgo get uploader      # currently selected uploader type
picgo get transformer   # currently selected transformer
picgo get plugins       # installed plugins and their enabled/disabled status

picgo get uploader

Read the current uploader type. Resolution order: picBed.uploader → picBed.current → picgo-cloud (fallback).

$ picgo get uploader
github

$ picgo get uploader --format json
{"uploader":"github"}

picgo get transformer

Read the current transformer. Defaults to path.

$ picgo get transformer
path

$ picgo get transformer --format json
{"transformer":"path"}

picgo get plugins

List installed plugins and their enabled/disabled status.

$ picgo get plugins
picgo-plugin-xxx    enabled
picgo-plugin-yyy    disabled

$ picgo get plugins --format json
{"plugins":[{"name":"picgo-plugin-xxx","enabled":true},{"name":"picgo-plugin-yyy","enabled":false}]}

If no plugins are installed:

$ picgo get plugins
No plugins installed.

TIP

In --format json mode, stdout contains a single JSON.parse-able line, making it easy to consume from scripts.

login 2.0+

Log in to PicGo Cloud (https://cloud.picgo.app) and persist the token to settings.picgoCloud.token.

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.

picgo logout

• Clears settings.picgoCloud.token locally.

cloud 3.0+

PicGo Cloud related commands, including auth status checks and cloud album management. All cloud subcommands require you to log in first via picgo login.

TIP

cloud login / cloud logout are aliases for picgo login / picgo logout. cloud config sync is an alias for picgo config sync.

cloud auth status

Check the current PicGo Cloud login status. Non-blocking — does not trigger an interactive login. Supports --format pretty|json (default pretty).

picgo cloud auth status [--format pretty|json]

The result is communicated via exit code, making it easy to use in scripts:

status	meaning	exit code
logged_in	token is valid	0
logged_out	no local token	1
invalid	token exists but was rejected by the server (401)	2
error	probe failed (network / server error)	3

• The logged_out path makes no network requests and returns instantly.
• When logged_in, the JSON output includes user and plan info.

$ picgo cloud auth status
Logged in as someone

$ picgo cloud auth status --format json
{"status":"logged_in","loggedIn":true,"user":"someone","plan":1}

Script usage example:

picgo cloud auth status --format json
if [ $? -ne 0 ]; then
  echo "Not logged in, running picgo login..."
  picgo login
fi

cloud album list

List items in the cloud album. Supports --format pretty|json (default pretty).

picgo cloud album list [options]

Options:

• --content-type <type> — filter by content type
• --type <uploader-type> — filter by uploader type (e.g. picgo-cloud, github, imgur)
• --ext <ext> — filter by file extension
• --search <keyword> — filter by keyword
• --file-name <name> — filter by file name
• --limit <limit> — page size
• --offset <offset> — page offset
• --sort <field> — sort field (newest / oldest / fileName)
• --order <order> — sort order (asc / desc)

$ picgo cloud album list --limit 5
┌────────────────────────┬──────────────────────────────┐
│ ID                     │ URL                          │
├────────────────────────┼──────────────────────────────┤
│ abc123                 │ https://picgocloud.com/m/... │
└────────────────────────┴──────────────────────────────┘
Total: 42  Limit: 5  Offset: 0

$ picgo cloud album list --type picgo-cloud --format json
{"success":true,"data":{"items":[...],"total":10,"limit":20,"offset":0}}

TIP

picgo cloud list is a shortcut for picgo cloud album list.

cloud album get

Get the details of a single cloud album item by ID.

picgo cloud album get <id> [--format pretty|json]

$ picgo cloud album get abc123
{
  "id": "abc123",
  "imgUrl": "https://picgocloud.com/m/xxx.jpg",
  "fileName": "test.jpg",
  ...
}

cloud album delete

Delete one or more cloud album items.

picgo cloud album delete <id...> [--force] [--format pretty|json]

• --force — skip the confirmation prompt.

$ picgo cloud album delete abc123 def456
? Are you sure you want to delete 2 items? (y/N)

$ picgo cloud album delete abc123 --force --format json
{"success":true,"data":{"deleted":["abc123"]}}

cloud album update

Update properties of a cloud album item.

picgo cloud album update <id> [options] [--format pretty|json]

Options:

• --fileName <name> — update file name
• --imgUrl <url> — update image URL
• --originImgUrl <url> — update original image URL
• --contentType <type> — update content type
• --width <width> — update width
• --height <height> — update height

$ picgo cloud album update abc123 --fileName new-name.jpg

cloud album import

Import local album data into PicGo Cloud's album. Three data sources are supported.

picgo cloud album import [dbPath] [options] [--format pretty|json]

Options:

• [dbPath] — local PicGo album database path (usually picgo.db); uses the default path if omitted
• --json-file <path> — read import data from a JSON file
• --data <json> — read import data from an inline JSON string
• --verbose — print batch details instead of a progress bar
• --enable-auto-import — enable auto-import if not already on

Requires a paid plan and auto-import to be enabled (or use --enable-auto-import).

$ picgo cloud album import
Import Summary:
  Total: 100  Created: 95  Skipped: 3  Invalid: 1  Failed: 0  Pending: 1

$ picgo cloud album import --json-file ./my-data.json --verbose

TIP

picgo cloud import is a shortcut for picgo cloud album import.

cloud album retry

Retry previously pending import items.

picgo cloud album retry [--verbose] [--format pretty|json]

$ picgo cloud album retry
Import Summary:
  Total: 5  Created: 4  Skipped: 0  Invalid: 0  Failed: 1  Pending: 0

config 2.0+

Manage config-related operations.

config sync

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.

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.

Specify an HTTP upload configuration 3.1.0+

Pass uploader, configName, or configId in the URL of POST /upload to use a saved uploader configuration for that request without changing local defaults. See Per-upload configuration for lookup scope and name/ID precedence.

# Upload by name. Keep the Authorization header if server authentication is enabled.
curl -X POST 'http://127.0.0.1:36677/upload?uploader=github&configName=Work' \
  -H 'Authorization: Bearer mytoken' \
  -H 'Content-Type: application/json' \
  -d '{"list":["/absolute/path/image.png"]}'

# You can also use a configuration ID. Replace it with the saved _id.
curl -X POST 'http://127.0.0.1:36677/upload?uploader=github&configId=your-config-id' \
  -H 'Authorization: Bearer mytoken' \
  -H 'Content-Type: application/json' \
  -d '{"list":["/absolute/path/image.png"]}'

These query parameters work with JSON file lists, multipart/form-data uploads, and clipboard uploads with an empty body. Successful responses retain the existing success, result, and items structure. The server checks authentication before validating upload options. Requests without these three parameters still use the existing default configuration.

Chinese configuration names are supported. Use URLSearchParams to encode Chinese characters, spaces, +, &, and other reserved characters, rather than concatenating them into the URL:

const url = new URL('http://127.0.0.1:36677/upload')
url.searchParams.set('uploader', 'github')
url.searchParams.set('configName', '配置一')

await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mytoken',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ list: ['/absolute/path/image.png'] })
})

Blank or repeated parameters, unregistered uploader types, missing configurations, and ambiguous matches return HTTP 400 in the following format. code and message explain the specific error. Authentication failures still return 401.

{
  "success": false,
  "result": [],
  "items": [],
  "code": "UPLOAD_CONFIG_AMBIGUOUS",
  "message": "The configuration name matches multiple uploader types. Specify uploader."
}

The message above is illustrative. Actual messages use the configured language and describe the lookup scope and matches. See Upload option errors for the error codes.

Multipart files are written to a temporary directory owned by the request. Files with the same name are stored separately, and the request's temporary files are removed after success or failure. Existing local paths passed in JSON are not deleted. Clipboard uploads only remove temporary images generated by PicGo, whose filenames retain the YYYYMMDDHHmmssSSS.png format.

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:

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, save the required uploader configuration with set. For uploads without configuration options, use use to set the default uploader. Starting with 3.1.0, you can also specify a saved configuration for just one upload.

$ 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.

$ 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

Specify a configuration for this upload 3.1.0+

upload and its alias u accept the following optional flags:

Flag	Description
--uploader <type>	Use the specified uploader type, such as github.
--configName <name>	Find a saved configuration by name. Recommended for everyday calls.
--configId <id>	Find a saved configuration by its _id.

# Upload a local file using a named configuration.
picgo upload ./image.png --configName="Work"

# Specify the uploader type when multiple types have the same configuration name.
picgo upload ./image.png --uploader=github --configName="Work"

# Upload by ID. Replace your-config-id with the saved _id.
picgo upload ./image.png --uploader=github --configId=your-config-id

# Try the name if the ID cannot be uniquely matched.
picgo upload ./image.png --configId=your-config-id --configName="Work"

# Without a file path, upload from the clipboard using the named configuration.
picgo upload --configName="Work"

# The alias and JSON output are still supported.
picgo u ./image.png --configName="Work" --format json

Both --configName="Work" and --configName "Work" are supported. Quote names that contain spaces. Passing only --uploader uses that type's active configuration. Without a type, the name or ID must uniquely match a configuration across registered uploaders. See Per-upload configuration for the full rules.

These options affect only this upload; they do not persistently switch configurations. Existing calls such as picgo upload ./image.png and picgo upload continue to use the default configuration. Local input files are not deleted after upload.

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:

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.

picgo uninstall [name]

update

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

picgo update [name]

i18n

Switch PicGo’s UI language. Supported languages:

• zh-CN (default)
• zh-TW
• en

Example:

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.

-p, --proxy 2.0+

Set a proxy URL for uploading. For example:

picgo u -p http://127.0.0.1:1080 test.jpg

The proxy URL is saved to the picBed.proxy config field.

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.

$ 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.