--- url: 'https://docs.picgo.app/core/guide/commands.md' --- # 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 set config path -h, --help output usage information Commands: install|add [options] install picgo plugin uninstall|rm uninstall picgo plugin update [options] update picgo plugin set [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`](https://github.com/PicGo/PicGo-Init) command instead (see `picgo-init` section below). ::: ::: tip 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](https://github.com/tj/commander.js/) and [inquirer.js](https://github.com/SBoudrias/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 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 ``` `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 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 ` * `picgo uploader copy ` (does not switch current uploader) * `picgo uploader rm ` 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] [name] [configName] configure config of picgo modules (uploader/transformer/plugin) Options: -h, --help output usage information ``` ::: tip Tip Most of the time you only need to configure an uploader. You can run `picgo set uploader` (or `picgo set uploader [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](https://github.com/Molunerfinn/PicGo/wiki/%E8%AF%A6%E7%BB%86%E7%AA%97%E5%8F%A3%E7%9A%84%E4%BD%BF%E7%94%A8)。 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! ``` ## login Log in to PicGo Cloud (https://cloud.picgo.app) and persist the token to `settings.picgoCloud.token`. ```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 Log out from PicGo Cloud (https://cloud.picgo.app) and clear the local token. ```bash picgo logout ``` * Clears `settings.picgoCloud.token` locally. ## config Manage config-related operations. ### config sync ```bash picgo config sync [--encrypt ] ``` * 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 `: validate `` as one of `auto`, `sse`, `e2ee`, then persist `settings.picgoCloud.encryptionMethod = ` 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 `` is invalid or missing, PicGo fails with: `Invalid configuration: settings.picgoCloud.encryptionMethod must be one of 'auto', 'sse', 'e2ee'. Found: ""`. * 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](https://picgo.app/blog/2026/picgo-configuration-sync-release/). ## server Run PicGo as a standalone local server. ```bash picgo server [options] ``` Options: * `-p, --port `: server port (default `36677`). * `-h, --host `: server host (default `127.0.0.1`). * `-i, --ignore-existing-external-server`: ignore an existing PicGo server on the same address. * `--secret `: 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 ` (case-insensitive) → `X-PicGo-Secret` → `?secret=`. * 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 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 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](https://www.npmjs.com/search?q=picgo-plugin-) 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 ` to specify the PicGo config file path. The default config file is `~/.picgo/config.json`. ::: tip 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`](https://github.com/PicGo/PicGo-Init) for installation and usage. ```bash $ picgo-init -h Usage: picgo-init