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
typefield (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
2means the app isn't running → go to Step 2. - Exit code
3means the GUI server has auth enabled → either pass--secret(seereferences/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. Checkpicgo cloud auth status --format json(see login below). Once logged in:
bash
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:
bash
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:
status |
exit | meaning | what to do |
|---|---|---|---|
logged_in |
0 | token valid | proceed to upload |
logged_out |
1 | no token | guide login (below) |
invalid |
2 | token expired/revoked | guide login (below) |
error |
3 | probe failed (network) | this is not "logged out" — don't push re-login; retry once, then report |
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:
bash
picgo login <token>
- If they don't have a token, login needs a browser. Do not run
picgo loginyourself — 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:
bash
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 jsonreturn 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:
(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).
