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

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!

get 3.0+

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

bash

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

bash

$ picgo get uploader
github

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

picgo get transformer

Read the current transformer. Defaults to path.

bash

$ picgo get transformer
path

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

picgo get plugins

List installed plugins and their enabled/disabled status.

bash

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

bash

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

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.

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

bash

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.

bash

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

bash

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

bash

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)

bash

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

bash

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

bash

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

bash

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

--force — skip the confirmation prompt.

bash

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

bash

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

bash

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

bash

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

bash

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

bash

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

bash

$ 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

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.

-p, --proxy 2.0+

Set a proxy URL for uploading. For example:

bash

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.

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.

How does it work?

Default config file

picBed

settings

get

cloud

config

Initialization

PicGo Cloud

Event listeners

Lifecycle plugins

Loading third-party plugins

CLI Commands ​

use ​

uploader 1.8.0+ ​

set ​

get 3.0+ ​

picgo get uploader ​

picgo get transformer ​

picgo get plugins ​

login 2.0+ ​

logout 2.0+ ​

cloud 3.0+ ​

cloud auth status ​

cloud album list ​

cloud album get ​

cloud album delete ​

cloud album update ​

cloud album import ​

cloud album retry ​

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 ​

-p, --proxy 2.0+ ​

picgo-init ​

CLI Commands

use

uploader 1.8.0+

set

get 3.0+

picgo get uploader

picgo get transformer

picgo get plugins

login 2.0+

logout 2.0+

cloud 3.0+

cloud auth status

cloud album list

cloud album get

cloud album delete

cloud album update

cloud album import

cloud album retry

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

-p, --proxy 2.0+

picgo-init