CLI命令

picgo 支持命令行模式直接使用。在你全局安装了picgo之后，你可以通过picgo -h来查看所有命令：

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

从 PicGo-Core v1.7.0 开始，PicGo 不再内置原来的 picgo init 命令。请使用独立的 picgo-init 命令（见下方 picgo-init 小节）。

提示

其中，命令选项如果是用<>包围起来的为必须输入项，如果是用[]包围起来的则为可选输入项。有些命令支持简写，比如picgo upload可以写为picgo u。

picgo 命令行的实现来自于commander.js与inquirer.js。下面将介绍各个命令以及如何配置。

use

该命令用于选择picgo模块。模块主要有三种：1. transformer 2. uploader 3. plugins

bash

$ picgo use -h

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

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

picgo内置了如下的内容：

transformer:
- path
- base64
uploader:
- smms -> SM.MS (S.EE)
- tcyun -> 腾讯云COS
- upyun -> 又拍云
- aliyun -> 阿里云OSS
- qiniu -> 七牛云
- imgur -> Imgur
- github -> GitHub

提示

通常来说，在命令行模式下你只需要选择path作为picgo的transformer即可。

具体使用可以通过picgo use 或者 picgo use uploader|transformer|plugins来选择你需要的模块内容，这将会进入一个交互式命令行：

bash

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

从 PicGo-Core v1.8.0 开始，uploader 支持多份命名配置。如果某个 uploader 存在多份配置，交互流程会让你选择要启用的那一份；你也可以直接在命令里指定：

bash

picgo use uploader <type> <configName>

其中 configName 的匹配大小写不敏感。

选择完后，picgo将会使用你选择的模块进行上传。在上传前有些模块可能需要配置。比如一些图床的key、token等。这个时候你就需要下面会提到的命令set来配置你选择的模块内容。

uploader 1.8.0+

用于管理 uploader 的多份命名配置。

picgo uploader：进入交互式管理（list/rename/copy/delete）
picgo uploader list [type]：列出配置（会标记当前 uploader 与默认配置）
picgo uploader rename <type> <oldName> <newName>
picgo uploader copy <type> <configName> <newConfigName>：复制配置（不会切换当前 uploader）
picgo uploader rm <type> <configName>

配置名匹配大小写不敏感。

示例：

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

该命令用于配置某些模块的一些配置项。模块主要有三种：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

提示

通常来说，picgo默认只需要配置Uploader即可。所以你可以直接通过picgo set uploader或者picgo set uploader <type> [configName]等命令直接进入交互式命令行。

从 PicGo-Core v1.8.0 开始，set uploader 支持 uploader 多配置：你可以选择一个已有的配置（按名称），也可以新建一份配置；保存后会自动将该配置设置为该 uploader 的当前启用配置。

picgo内置的图床的配置项细节可以参考PicGo的配置wiki。

如果某个uploader或者transformer或者plugin没有可配置项，picgo也会提示配置成功，不需要担心。

bash

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

get 3.0+

读取当前选中的 picgo 模块配置。支持三个子命令，均支持 --format pretty|json（默认 pretty）。

bash

picgo get uploader      # 当前选中的 uploader 类型
picgo get transformer   # 当前选中的 transformer
picgo get plugins       # 已安装插件及启用/禁用状态

picgo get uploader

读取当前使用的 uploader 类型。取值逻辑：picBed.uploader → picBed.current → picgo-cloud（兜底）。

bash

$ picgo get uploader
github

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

picgo get transformer

读取当前使用的 transformer。默认值为 path。

bash

$ picgo get transformer
path

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

picgo get plugins

列出已安装的插件及其启用/禁用状态。

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

如果没有安装任何插件：

bash

$ picgo get plugins
没有已安装的插件。

TIP

--format json 模式下，stdout 只输出一行可直接 JSON.parse 的 JSON，适合在脚本中解析。

bash

picgo login [token]

传入 token：通过 Cloud API 验证，成功后保存。
不传 token：先尝试已保存的 token；无效则开启浏览器登录流程。
浏览器登录会启动本地回调服务并打开 https://cloud.picgo.app 的登录 URL；若无法自动打开，会打印 URL 供手动打开。

logout 2.0+

退出 PicGo Cloud（https://cloud.picgo.app），并清除本地 token。

bash

picgo logout

清除本地保存的 settings.picgoCloud.token。

cloud 3.0+

PicGo Cloud 相关命令，包括认证状态检查、云相册管理等。所有 cloud 子命令都需要先通过 picgo login 登录。

TIP

cloud login / cloud logout 是 picgo login / picgo logout 的别名，功能完全相同。cloud config sync 是 picgo config sync 的别名。

cloud auth status

检测当前 PicGo Cloud 的登录状态。非阻塞，不会触发交互式登录。支持 --format pretty|json（默认 pretty）。

bash

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

通过 exit code 输出结果，便于脚本判断：

status	含义	exit code
`logged_in`	token 有效	`0`
`logged_out`	本地无 token	`1`
`invalid`	有 token 但被服务端拒绝（401）	`2`
`error`	探测失败（网络 / 服务端错误）	`3`

logged_out 路径完全不发网络请求，瞬间返回。
logged_in 时返回的 JSON 包含 user 和 plan 信息。

bash

$ picgo cloud auth status
Logged in as someone

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

脚本用法示例：

bash

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

cloud album list

列出云相册中的项目。支持 --format pretty|json（默认 pretty）。

bash

picgo cloud album list [options]

选项：

--content-type <type> — 按内容类型筛选
--type <uploader-type> — 按上传器类型筛选（如 picgo-cloud、github、imgur）
--ext <ext> — 按文件扩展名筛选
--search <keyword> — 按关键字筛选
--file-name <name> — 按文件名筛选
--limit <limit> — 分页大小
--offset <offset> — 分页偏移量
--sort <field> — 排序字段（newest / oldest / fileName）
--order <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 是 picgo cloud album list 的快捷方式，功能完全相同。

cloud album get

获取指定 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

删除一个或多个云相册项目。

bash

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

--force — 跳过确认提示，直接删除。

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

更新指定 ID 的云相册项目属性。

bash

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

选项：

--fileName <name> — 更新文件名
--imgUrl <url> — 更新图片 URL
--originImgUrl <url> — 更新原始图片 URL
--contentType <type> — 更新内容类型
--width <width> — 更新宽度
--height <height> — 更新高度

bash

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

cloud album import

将本地相册数据导入到 PicGo Cloud 的云相册。支持三种数据源。

bash

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

选项：

[dbPath] — 本地 PicGo 相册数据库路径（通常为 picgo.db），不指定则使用默认路径
--json-file <path> — 从 JSON 文件读取导入数据
--data <json> — 从内联 JSON 字符串读取导入数据
--verbose — 打印批处理详情（而非进度条）
--enable-auto-import — 需要时自动启用自动导入功能

需要付费套餐且已启用自动导入功能（或使用 --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 是 picgo cloud album import 的快捷方式，功能完全相同。

cloud album retry

重试之前导入时未成功的待处理项目。

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+

配置相关操作，目前包含 config sync。

config sync

bash

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

使用三路合并（snapshot + local + remote）同步配置。
首次同步或远端缺失时，使用本地配置回填云端并生成 snapshot。
发生冲突时会打印 diff tree 并提示 Use Local / Use Remote / Abort；在你选择前不会覆盖本地配置。
settings.picgoCloud.token 与 settings.picgoCloud.encryptionMethod 仅保留本地值，不会被云端覆盖。
需要有效的 Cloud token，先运行 picgo login（cloud.picgo.app）。

加密方式选项

--encrypt <method>：校验 <method> 必须为 auto、sse、e2ee 之一，并在同步前写入 settings.picgoCloud.encryptionMethod = <method>。
三种模式说明：auto 会跟随云端上一次保存的加密方式，sse 为服务端加密，e2ee 为端到端加密（需要 PIN）。
若 <method> 非法或缺失，PicGo 会报错：Invalid configuration: settings.picgoCloud.encryptionMethod must be one of 'auto', 'sse', 'e2ee'. Found: "<value>"。
不带参数时，遵循本地偏好（settings.picgoCloud.encryptionMethod）；缺失时默认 auto，但不会写回配置。
使用 E2EE 时会要求输入 PIN（需二次确认，最多重试 3 次）；解密时 PIN 错误会最多再重试 3 次，超过后失败。
详细说明可参考 PicGo Blog。

server 2.0+

以本地 HTTP 服务方式运行 PicGo。

bash

picgo server [options]

参数：

-p, --port <n>：服务端口（默认 36677）。
-h, --host <s>：服务 host（默认 127.0.0.1）。
-i, --ignore-existing-external-server：忽略同地址的 PicGo 实例。
--secret <s>：开启服务鉴权的 shared secret。

当端口被占用时，PicGo 会检测是否已有 PicGo 实例；若存在则复用端口（除非指定 --ignore-existing-external-server），否则端口自增重试。

内置接口

POST /heartbeat → { success: true, result: "alive" }
POST /upload
- 空 body、{} 或 { "list": [] }：上传剪贴板。
- { "list": ["path1", "path2"] }：上传指定文件路径。
- 非法 JSON 返回 HTTP 400。
- multipart/form-data 且字段为 files：上传文件并清理 baseDir 下的临时文件。

指定 HTTP 上传配置 3.1.0+

在 POST /upload 的 URL 中传入 uploader、configName 或 configId，即可为本次请求指定已经保存的图床配置，不需要修改本地默认配置。配置名称和 ID 的查找范围、优先级见单次上传配置。

bash

# 按名称上传；服务开启鉴权时需要保留 Authorization 请求头。
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"]}'

# 也可以用配置 ID。请替换为实际保存的 _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"]}'

这些 URL 参数同时适用于 JSON 文件列表、multipart/form-data 文件上传和空 body 的剪贴板上传。成功时保留原有的 success、result 和 items 响应结构。服务器会先检查鉴权，再校验上传参数；没有提供这三个参数时，仍使用原来的默认配置。

中文配置名也受支持。建议使用 URLSearchParams 编码中文、空格、+、& 等字符，避免手动拼接导致参数含义改变：

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'] })
})

空白参数、同一参数重复出现、图床类型未注册、配置不存在或无法唯一定位时，服务器返回 HTTP 400，格式如下。code 和 message 会说明具体原因；未通过鉴权时仍返回 401。

json

{
  "success": false,
  "result": [],
  "items": [],
  "code": "UPLOAD_CONFIG_AMBIGUOUS",
  "message": "配置名称匹配到多个图床类型，请指定 uploader。"
}

上面的 message 仅为示意，实际内容会按语言设置说明查找范围与匹配结果。错误码列表见上传参数错误。

multipart 文件会写入本次请求独立的临时目录，同名文件也会各自保存，上传完成或失败后清理该请求的临时文件。JSON 中传入的已有本地路径不会因此被删除；剪贴板上传只清理 PicGo 自己生成的临时图片，文件名仍是 YYYYMMDDHHmmssSSS.png。

鉴权（可选）

当解析到非空 secret 时启用鉴权（优先级：--secret → PICGO_SERVER_SECRET → settings.server.secret）。secret 会先 trim；仅空白将禁用鉴权。

保护路由：POST /upload 与所有插件注册路由（含 mount 子路由）。
凭证优先级：Authorization: Bearer <token>（大小写不敏感）→ X-PicGo-Secret → ?secret=<token>。
- 只要存在 Authorization，即使错误也不会回退到低优先级来源。
- ?secret= 可用但不推荐；服务进程只会警告一次。
未授权返回 HTTP 401 与 { success: false, message: "Unauthorized" }。
启动时会记录是否启用了鉴权；未授权请求会记录客户端 IP（优先 X-Forwarded-For）。

示例：

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

该命令用于上传图片到图床。通常是上传磁盘上已有的图片，可以同时上传多张。上传多张图片的时候用空格隔开。也可以上传剪贴板里的第一张图片。

提示

请确保上传前已通过 set 命令保存所需的图床配置。不传上传选项时，可以用 use 设置默认图床；从 3.1.0 开始，也可以只为本次上传指定已有配置。

bash

$ picgo u ./Test-测试.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

如果不显式指定上传的文件，picgo将会上传剪贴板里的第一张图片（由于跨平台限制，上传时将会转为png格式）。通常这在截图后上传非常有用。

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

指定本次上传的配置 3.1.0+

upload 和简写 u 支持以下可选参数：

参数	说明
`--uploader <type>`	使用指定图床类型，例如 `github`。
`--configName <name>`	按已保存的配置名称查找，推荐用于日常调用。
`--configId <id>`	按已保存配置的 `_id` 查找。

bash

# 上传本地文件，按名称查找配置。
picgo upload ./image.png --configName="配置一"

# 不同类型存在同名配置时，指定图床类型。
picgo upload ./image.png --uploader=github --configName="配置一"

# 按配置 ID 上传；your-config-id 需要替换为实际的 _id。
picgo upload ./image.png --uploader=github --configId=your-config-id

# ID 无法唯一匹配时，再尝试配置名称。
picgo upload ./image.png --configId=your-config-id --configName="配置一"

# 不传文件路径，使用指定配置上传剪贴板图片。
picgo upload --configName="配置一"

# 仍然支持简写和 JSON 输出。
picgo u ./image.png --configName="配置一" --format json

--configName="配置一" 与 --configName "配置一" 两种写法都支持。名称包含空格时需要加引号。只传 --uploader 会使用该类型当前启用的配置；省略类型时，名称或 ID 必须在所有已注册图床中唯一匹配。完整规则见单次上传配置。

这些选项只影响本次上传，不会执行持久化切换。原来的 picgo upload ./image.png 和 picgo upload 继续使用默认配置，本地输入文件也不会在上传后删除。

install|add

该命令用于安装npm上的picgo的插件。picgo的插件名都是以picgo-plugin-开头的。在安装、卸载或者更新的时候，你只需要输入name值而不需要输入picgo-plugin-的前缀。可以一次性安装多个插件，用空格隔开即可。

提示

PicGo会把插件安装在配置文件所在的目录下。默认配置文件在~/.picgo/下，所以插件会安装在~/.picgo/node_modules/下。

你可以通过npm的官方网站查找目前所有的picgo的插件。picgo的插件命名规则为picgo-plugin-[name]。然后再通过：

bash

picgo install [name]

来安装插件。你安装了之后，可以通过picgo ch plugins来选择开启或者禁用这个插件。

uninstall|rm

该命令用于删除你所安装的picgo插件。如果不存在将会报错。

bash

picgo uninstall [name]

update

该命令用于更新已经安装的picgo插件。如果不存在将会报错。

bash

picgo update [name]

i18n

用于切换 picgo 的语言。目前支持的语言有：

zh-CN (默认)
zh-TW
en

示例：

bash

picgo i18n en

-v, --version

输入picgo -v或者picgo --version将输出当前picgo的版本信息。

-d, --debug

在输入任何有效命令的情况下加入-d或者--debug会进入debug模式。将会输出更加详细的报错信息，指出错误的具体位置。

-c, --config

在输入任何有效命令的情况下加入-c <path>可以指定picgo的配置文件所在处。默认的配置文件是~/.picgo/config.json。

提示

picgo将会读取配置文件所在目录下node_modules的插件。

-s, --silent

在输入任何有效命令的情况下加入-s或者--silent将会进入静默模式，除了报错信息之外，picgo在命令行里将不会输出任何信息。

-p, --proxy 2.0+

设置上传时使用的代理地址。例如：

bash

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

代理地址会被写入 picBed.proxy 配置项。

picgo-init

该命令用于下载和生成 picgo 的插件开发模板

从 PicGo-Core v1.7.0 开始，该能力由独立的 picgo-init 命令提供。你可以在 PicGo/PicGo-Init 找到安装与使用说明。

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

类似于vue-cli的init命令，picgo 也提供了官方模板。你在执行 picgo-init 时，模板名只需要写 plugin，内部会自动判断如果非 username/repo 形式的话，自动加上 PicGo/picgo-template- 的前缀。

这个命令用于方便用户快速开发一个picgo插件。关于插件开发，可以查看插件开发一章。

它是如何工作的？

默认配置文件

picBed

settings

get

cloud

config

server

upload|u

初始化

上传

PicGo Cloud

事件监听

生命周期插件

加载第三方插件

CLI命令 ​

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 ​

加密方式选项 ​

server 2.0+ ​

内置接口 ​

指定 HTTP 上传配置 3.1.0+ ​

鉴权（可选） ​

upload|u ​

指定本次上传的配置 3.1.0+ ​

install|add ​

uninstall|rm ​

update ​

i18n ​

-v, --version ​

-d, --debug ​

-c, --config ​

-s, --silent ​

-p, --proxy 2.0+ ​

picgo-init ​

CLI命令

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

加密方式选项

server 2.0+

内置接口

指定 HTTP 上传配置 3.1.0+

鉴权（可选）

upload|u

指定本次上传的配置 3.1.0+

install|add

uninstall|rm

update

i18n

-v, --version

-d, --debug

-c, --config

-s, --silent

-p, --proxy 2.0+

picgo-init