Picgo Upload

PicGo Upload

Turn a local image or file into a hosted, shareable URL using PicGo. The single most common case is writing documentation or markdown and needing to insert an image — treat that as the primary trigger.

When to use

Reach for this skill when the user wants a link for a local image or file and hasn't named a specific destination platform:

• Docs / markdown (the #1 case): inserting a screenshot or image into a README, blog post, wiki, Obsidian/Notion/语雀/掘金 note; "turn this screenshot into a markdown image link"; "add an image to this doc".
• Any image/screenshot that needs a shareable or embeddable URL.
• Any file (PDF, zip, installer, etc.) that needs a public download link.
• The user says "传图床", "图床", "upload this image", "host this file".

When NOT to use

• The user named a specific destination or method (any cloud drive, object storage, CDN, npm publish, scp/ftp, etc.) → use the tool for that platform instead.
• Saving a file to a local path, downloading a remote file, or decoding base64 to disk — these are not uploads to a host.
• Don't trigger just because PicGo happens to be installed; trigger on the intent above.

Upload routing (try in this order)

There are three ways to upload. Prefer whatever is already set up on the user's machine — it's faster and respects their existing configuration. Fall back to recommending PicGo Cloud only when nothing is ready.

Step 1 — PicGo desktop app (if running)

If the user has the PicGo desktop app open, its local server can upload with zero install and zero login, reusing whatever image hosting they configured in the GUI.

Use the bundled script (it probes the server first and returns nothing if the app isn't running):

node scripts/gui-upload.mjs /abs/path/to/image.png

• On success it prints a JSON array [{ "imgUrl": "...", "type": "...", ... }].
• Tell the user which host was used, read from the type field (e.g. "Uploaded via your PicGo app (GitHub uploader)"). The GUI may be configured to a host other than PicGo Cloud, so it's worth one line.
• Exit code 2 means the app isn't running → go to Step 2.
• Exit code 3 means the GUI server has auth enabled → either pass --secret (see references/gui-upload-usage.md) or just fall back to Step 2.

See references/gui-upload-usage.md for clipboard uploads, ports, and secrets.

Step 2 — Make sure the PicGo CLI is available

Check if picgo is installed and has the cloud commands:

picgo get uploader --format json

If this fails with "unknown command" or picgo isn't found, the CLI is missing or too old. Install the latest globally, then continue:

npm install picgo -g

If the install fails (commonly an EACCES permission error), don't try sudo automatically — show the user the command to run themselves (e.g. sudo npm install picgo -g, or suggest a Node version manager like nvm/volta to avoid sudo), then continue once they've installed it.

Step 3 — Upload via the CLI (optimistic)

Step 2 already told you which uploader is active (from the picgo get uploader output).

• If it's picgo-cloud, the user needs to be logged in. Check picgo cloud auth status --format json (see login below). Once logged in:

  picgo upload /abs/path/to/file --format json
  

• If it's anything else (github, smms, a custom image hosting the user already set up), just upload — no PicGo Cloud login needed:

  picgo upload /abs/path/to/file --format json
  

picgo upload --format json prints [{imgUrl, fileName, type, size, ...}], the same shape the GUI script returns.

PicGo Cloud login

When the active image hosting is picgo-cloud and the user isn't logged in, picgo cloud auth status --format json returns one of:

To log in:

• If the user already has a token (e.g. copied from the PicGo Cloud web dashboard), it's non-interactive and instant:

  picgo login <token>
  

• If they don't have a token, login needs a browser. Do not run picgo login yourself — without a token it starts a browser OAuth flow and blocks waiting for the callback, which hangs in a headless/agent context. Instead, ask the user to run it in their own terminal and tell you when done:

  picgo login
  

PicGo Cloud has a free tier that's plenty for casual first use.

Output

• Internally, both the GUI script and picgo upload --format json return the same JSON array shape: [{imgUrl, fileName, type, size, width, height, ...}].
• Default to returning the bare URL. When the context is clearly markdown or a document, return a markdown image instead: ![](imgUrl) (use a sensible alt text). For non-image files, a plain link is right.
• For multiple files, results map to inputs in order. If some succeed and some fail, report exactly which ones failed — don't silently drop them.
• Don't copy anything to the clipboard; PicGo handles that itself.

Public-link safety

PicGo Cloud links are publicly accessible — anyone with the URL can open it, and a deleted file may still be cached. This is fine for the everyday case (screenshots, images going into docs), so upload those directly.

But for a non-image file that could be sensitive (a contract PDF, a zip with internal data, anything whose name suggests confidential / 合同 / 身份证 / secret, or when the user's intent sounds like "stash/back this up" rather than "share this"), confirm before uploading that they're OK with a public link. When you return any link, note that it's publicly accessible.

Clipboard uploads

PicGo can upload the image currently in the clipboard, but only do this when the user explicitly mentions the clipboard or a screenshot ("upload my clipboard image", "传剪贴板里的图", "host the screenshot I just took"). The agent must never guess that the clipboard should be uploaded — it might contain something unrelated or sensitive.

• GUI app running: node scripts/gui-upload.mjs --clipboard
• CLI: picgo upload (no path argument uploads the clipboard)

If the user only says "upload an image" without a path and without mentioning the clipboard, ask where the image is (path, or whether they mean the clipboard) rather than guessing. Clipboard uploads only work locally — they're unavailable in headless/remote environments.

Errors

Upload failures are not all alike: most PicGo Cloud business errors (not logged in, file type not allowed, quota exceeded) are not worth retrying — only network/5xx errors are. See references/error-handling.md for the triage table. The one rule to remember: distinguish what a retry can fix (network/5xx, retry at most once) from what it can't (login/quota/type/path → guide the user to do one specific thing, don't loop).