gitpic
/gitpic
Wgrywa lokalny obraz lub obraz ze schowka do repozytorium GitHub jako hostingu grafik i zwraca link w markdown, przy użyciu CLI gitpic.
- Autor
- tarnish233 ↗
- Repozytorium
- gitpic ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 05.09.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 9
Brak sygnałów. Repozytorium zmienione 05.09.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Wgrywa lokalny obraz lub obraz ze schowka do repozytorium GitHub jako hostingu grafik i zwraca link w markdown, przy użyciu CLI gitpic.
Wyzwalacze z opisu
Oryginalny opis (EN)
Upload a local or clipboard image to a GitHub repo (image host) and return a Markdown link. Use when the user wants to "upload an image", "turn this image into a link", "host an image", "get a markdown link for a screenshot", "把图片上传图床", or "生成图片 markdown 链接". Requires the `gitpic` CLI installed and authenticated with `gitpic auth login` (install gitpic from https://github.com/tarnish233/gitpic/releases).
Jak działa
- Installation
- 0. Preflight
- 0b. Which repository (only when the target is wrong or unset)
- 0c. Which branch (only when the branch is wrong, or the user asks for another)
- 1. Upload a local image
- 2. Upload multiple images
- 3. Upload raw bytes (no file path)
- 4. Upload an image explicitly requested from the clipboard
- 5. Other useful commands
- Output schema (success)
Podgląd SKILL.md
---
name: gitpic
description: >-
Upload a local or clipboard image to a GitHub repo (image host) and return a
Markdown link. Use when the user wants to "upload an image", "turn this image
into a link", "host an image", "get a markdown link for a screenshot",
"把图片上传图床", or "生成图片 markdown 链接". Requires the `gitpic` CLI installed
and authenticated with `gitpic auth login` (install gitpic from
https://github.com/tarnish233/gitpic/releases).
---
# gitpic — GitHub image host uploader
`gitpic` uploads an image to a GitHub repository (used as an image host) and
prints a Markdown link. It is human/agent dual-mode: always pass `--json` when
calling it programmatically, and `--no-copy` on the upload commands.
## Installation
First check whether the CLI exists: `command -v gitpic`. If it is missing,
install it one of these ways, then verify with `gitpic --version`:
- Prebuilt binary — the one you can do yourself: download the matching asset from
the latest [release](https://github.com/tarnish233/gitpic/releases), extract, and put
`gitpic` on `PATH`. On macOS clear the quarantine flag first:
```bash
xattr -d com.apple.quarantine ./gitpic 2>/dev/null; chmod +x ./gitpic
```
- If the user already has GitPic.app, the same CLI is inside it: ask them to open
设置 ▸ 通用 ▸ 命令行 and click 安装命令行工具. That links `~/.local/bin/gitpic` into
the app bundle, so it tracks every app update instead of going stale, and it installs
shell completions. You cannot click it for them.
- From source (needs Rust 1.88 or newer):
```bash
cargo install --git https://github.com/tarnish233/gitpic
```
Authentication comes from `gitpic auth login` and nowhere else. There is no `gh`
fallback, no `GITPIC_TOKEN`, and no way to pass a token on a command line — so do not
probe for `gh`, do not suggest installing it, and do not ask the user for a token.
`gitpic doctor --json` answers the only question that matters.
When there is no credential, **hand the user the command and stop**:
```
gitpic auth login
```
You cannot run it for them. It prints a one-time code they have to type at
<https://github.com/login/device> and then waits for a browser, so running it yourself
would block on a code only they can enter. Its `--json` is not an envelope but a
line-per-event stream (see Constraints), so it is not the shape the rest of this
document's `--json` advice assumes either.
Once they say they are done, confirm with `gitpic auth status --json` — `ok` and
`token_valid` say whether the credential works, and the report also carries `login`,
`client_id`, `expires_at` and the credential's `path`. Then re-run the preflight.
## 0. Preflight
Run the health check before the first upload in a session:
```bash
gitpic doctor --json
```
Parse stdout JSON. An unhealthy report carries an `error` object in the same
`{ code, message }` shape every other subcommand uses, and exits non-zero with the
same code. **Read `error.code`, not the exit status** — piping the output to a
parser (`gitpic doctor --json | jq`) replaces the exit status with the parser's own,
and some harnesses never surface it at all. `error` is present on exactly the
reports where `ok` is false. The report also carries `login` (the account `/user`
confirmed, absent when that probe did not succeed) and `detail`, the same text as
`error.message`.
Require `config_ok`, `token_valid`, and `repo_writable` to be `true`. If `config_ok`
is false, run `gitpic repos --json` (§0b) and offer the user the repositories it lists —
`gitpic config set github.repo owner/name github.branch <that repo's default_branch>`
writes the choice (§0c lists the branches if the user wants one that is not the default), and `GITPIC_REPO=owner/name` (plus `GITPIC_BRANCH`,
`GITPIC_LINK=cdn|raw`) sets it for one run. Then stop. Set the branch from the listing
rather than leaving it: a repository whose default is `master` configured for `main`
fails every upload on a ref that is not there. If `token_valid`
is false and `repo_writable` is also false, hand the user `gitpic auth login` and stop.
`repo_writable: false` with `token_valid: true` usually means the repository is absent,
the credential cannot reach it, or the account lacks write access. Run `gitpic repos --json`
to tell those apart. If the repo is present with `can_push: false`, another login will not
repair the account's permissions. If it has `private: true`, do **not** widen the OAuth scope
and retry: GitPic's links carry no credential, so private repositories are rejected as image
hosts even when the Contents API write itself would be allowed. Ask the user to choose a
public repository instead.
`repo_writable` means **both** that the token may push to the repository **and**
that the target branch exists. When it is false, `error.code` narrows it down but does
not settle it — read `error.message` too:
- `PERMISSION_DENIED` (7): the repository answered, and GitHub reports no push or admin
permission. The app's access to that repository, or its Contents read/write
permission, is what needs fixing.
- `REMOTE_NOT_FOUND` (8): **two** causes, told apart by the message. `target branch does
not exist on the remote` means the repository is fine and only the ref is absent —
create it or change `github.branch`. A message quoting GitHub's own 404 (`GitHub
repository, branch, or remote path not found`) means the repository is invisible to the
app, which is the install/authorise case above; creating a branch will not help.
`detail` carries the same text as `error.message` either way.
The two GitHub checks are probed independently — and only when `config_ok` is true, so
read `config_ok` first. When they did not run at all, `token_valid` and `repo_writable`
are **`null`**, not `false`: that is the state of a machine that has logged in but not yet
chosen a repository, and `false` there was a claim about a credential nothing had looked
at — `gitpic auth status --json` on that same machine reports it working. `null` is not
`true`, so requiring `true` above is unaffected; what changes is that you must not read
`token_valid: null` as a reason to send the user to log in again. If
`token_valid` is false **but `repo_writable` is true** and `error.code` is
`NETWORK`, the credential is fine and GitHub's `/user` endpoint — which uploads
never call — is simply unreachable. Retry; do not send the user to
another login, which cannot fix it. Treat `token_valid: false` as a credential
problem only when `repo_writable` is also false.
`branch_protected: true` is a caveat, not a failure: the branch has protection
rules, which may still permit this account, so a report can be `ok: true` with it
set. It is the usual explanation when an upload is nevertheless refused with
`PERMISSION_DENIED` or a 422 after every preflight check passed — if that
happens, say so rather than retrying. A 409 ref conflict is `NETWORK` (5):
retry once, then report.
`detail` also carries non-fatal caveats, currently branch protection. Two setup states
are hard `USAGE` failures instead: any **private** repository, because neither emitted link
form authenticates its visitor; and `link_kind = "cdn"` with a `github.branch` containing
`/`, because jsDelivr cannot tell that branch apart from the file path. `doctor` reports the
same failure the upload path would rather than calling either configuration healthy.
There is one credential source, so the report carries no `token_source` field: a
credential either works (`token_valid: true`) or the user has not run `gitpic auth login`.
No subcommand accepts a token, and there is no `gitpic init` — the repository is chosen at
the end of `gitpic auth login`, which only a human can run.
## 0b. Which repository (only when the target is wrong or unset)
```bash
gitpic repos --json
```
```json
{ "ok": true, "complete": true, "repos": [
{ "owner": "octocat", "name": "img", "private": false,
"default_branch": "main", "can_push": true } ] }
```
Every repository the credential can reach, alphabetical. Use it to answer "which repo
should this go to" instead of guessing an `owner/repo`, and to explain a
`REMOTE_NOT_FOUND` that a hand-typed target caused.
- `can_push: false` means the account cannot write there — offer it, do not silently drop
it, but say so.
- `private: true` repositories are diagnostic rows only; do not offer them as image-host
choices, because the returned URLs are unauthenticated and will not resolve for recipients.
- `complete: false` means the listing hit its page ceiling, so a repository the user names
may exist without appearing. Say that rather than reporting it as absent.
- `default_branch` is what `github.branch` should be — do not assume `main`.
Set the target with `gitpic config set github.repo owner/name --json` (add
`github.branch <default_branch>` in the same call when it is not `main`).
## 0c. Which branch (only when the branch is wrong, or the user asks for another)
```bash
gitpic branches --json # the configured repository
gitpic branches --repo owner/name --json # any repository
```
```json
{ "ok": true, "repo": "octocat/img", "configured": "main", "complete": true,
"branches": [ { "name": "main", "protected": true },
{ "name": "images", "protected": false } ] }
```
Uploads go through the Contents API, which **cannot create a branch**. So the legal values
for `github.branch` are exactly the names in `branches`, and a value outside that list
fails every upload with `REMOTE_NOT_FOUND` — GitHub answers 404 for a missing ref, the same
as for a repository it cannot see, which is why guessing a branch name produces the least
informative failure gitpic has.
- `configured` is the branch an upload would use right now, resolved by the CLI (so it
reflects `GITPIC_BRANCH`). When it is **not** in `branches`, that is the whole finding:
say so and offer the listed names. Do not report it as a permissions problem.
- `protected: true` does **not** mean unwritable — the rules may permit this account. Never
filter a protected branch out of what you offer. It is worth naming only when an upload
has already failed with `PERMISSION_DENIED` or a 422 after every check passed.
- An empty `branches` with `ok: true` is a repository with no commits. The first upload
creates the ref, so this is not an error and needs no fix.
- `complete: false` means the page ceiling was hit; a branch the user names may exist
without appearing.
Change it with `gitpic config set github.branch <name> --json`.
## 1. Upload a local image
```bash
gitpic "/absolute/path/to/image.png" --json --no-copy
```
Parse stdout JSON and return `results[0].markdown` to the user. Other useful
fields: `url`, `raw_url`, `html`, `path`, `deduped`.
## 2. Upload multiple images
```bash
gitpic "/abs/a.png" "/abs/b.jpg" --json --no-copy
```
`results` is an array with one record per file.
## 3. Upload raw bytes (no file path)
```bash
cat image.png | gitpic --stdin --json --no-copy
```
Use this when you only have image bytes (e.g. a screenshot buffer). The extension
is derived from the bytes themselves, so JPEG data is never published at a `.png`
path — `--name` supplies the filename stem, and its extension is ignored.
**Bytes gitpic cannot identify are the one exception**, because then there is
nothing to derive an extension from: `--name` must carry one and is honoured.
`--name shot.bin` works; `--name shot` and no `--name` at all are both a `USAGE`
error (2) rather than a guessed `.png`. So do not strip the extension when
retrying a stdin upload that asked for `--name`.
## 4. Upload an image explicitly requested from the clipboard
```bash
gitpic paste --json --no-copy
```
Use `paste` only when the user explicitly asks for the current clipboard image
and the execution environment has clipboard access. Otherwise prefer a local
absolute path or stdin.
## 5. Other useful commands
```bash
gitpic big.png --compress --max-width 1600 --json --no-copy # shrink before upload
gitpic big.jpg --compress --quality 80 --json --no-copy # JPEG quality (1-100)
gitpic photo.png --link raw --json --no-copy # force raw GitHub URL
gitpic list --json # recent uploads (history)
```
## Output schema (success)
```json
{ "ok": true, "results": [ {
"name": "shot", "url": "https://cdn.jsdelivr.net/gh/owner/repo@main/images/...",
"raw_url": "https://raw.githubusercontent.com/owner/repo/main/images/...",
"markdown": "", "html": "<img src=\"...\" alt=\"shot\">",
"path": "images/2026/07/ab12cd34-shot.png", "sha": "…", "size": 20481,
"deduped": false, "output": "" } ] }
```
## Error handling (exit code / error.code)
| exit | error.code | agent action |
|------|---------------------|---------------------------------------------------|
| 1 | GENERAL | unexpected failure — report `error.message` |
| 2 | USAGE | fix the invocation |
| 3 | CONFIG_MISSING | hand the user `gitpic auth login`, or configure the target repo |
| 4 | AUTH_FAILED | credential invalid/expired — hand the user `gitpic auth login` |
| 5 | NETWORK | retry once, then report (includes a 409 ref conflict) |
| 6 | NOT_FOUND | check the local input file path |
| 7 | PERMISSION_DENIED | check token Contents permission/repo access |
| 8 | REMOTE_NOT_FOUND | check GitHub repository, branch, and remote path — `gitpic branches --json` (§0c) separates "the branch is not there" from "the repo is not there", which the 404 itself does not |
| 9 | RATE_LIMITED | wait or ask the user before retrying later |
| 10 | CONFIG_INVALID | the config file is broken — tell the user to run `gitpic config edit`; `error.message` names the file plus the rejected key or the parser's complaint, but not a line number |
Error JSON: `{ "ok": false, "error": { "code": "AUTH_FAILED", "message": "…" } }`
`gitpic doctor` carries the same `error` object alongside its report fields, so the
code is always on stdout — never depend on the exit status alone.
Do not confuse 3 with 10. `CONFIG_MISSING` covers two "nothing is set up yet" states
and `error.message` says which: `missing target repo` is yours to fix with
`gitpic config set github.repo` or `GITPIC_REPO=owner/name`, while `no GitHub credential`
is fixed only by handing the user `gitpic auth login` — setting a repository there
reconfigures a target that was never the problem. `CONFIG_INVALID` means the file exists
but has bad syntax or an unknown key — neither of those commands fixes it, and retrying
will loop.
## Partial success (multiple images)
Uploads run serially. If an image fails after earlier ones succeeded, the exit
code is that of the failure, but `results` still lists every image that did
upload — those links are live and must not be discarded:
```json
{ "ok": false,
"results": [ { "name": "one", "markdown": "", "…": "…" } ],
"error": { "code": "RATE_LIMITED", "message": "…" } }
```
Report the successful links, then handle `error.code` per the table above for the
remaining images. When no image uploaded, the plain error JSON above is returned
instead — `results` is never present and empty.
## Constraints
- Always pass `--json` for programmatic calls, and `--no-copy` on the upload
commands only (`gitpic <files>`, `--stdin`, `paste`). Upload-only options
(`--no-copy`, `--link`, `--format`, `--name`, `--path`, `--compress`,
`--no-compress`, `--max-width`, `--quality`, `--stdin`, `--repo` except on
`doctor`) are not accepted on other subcommands — clap rejects them, exit 2 —
and they must be written **after** the subcommand: `gitpic paste --json
--no-copy`, never `gitpic --no-copy paste`, which is a `USAGE` error (2).
`--json`, `--quiet` and `--verbose` work on either side of it.
`--name` is for stdin, paste, or a single file; with two or more files it is a
`USAGE` error. It supplies only the filename *stem* in all three cases — the
extension always follows the image bytes, so `--name shot` or `--name shot.png`
on JPEG bytes both publish `shot.jpg`. Never rely on `--name` to set the
extension — with one exception, `--stdin` over bytes gitpic cannot identify,
where it is the only source there is and must include one (see §3).
`gitpic config set` accepts `KEY VALUE` pairs in one invocation
(`gitpic config set github.owner me github.repo pics --json`) and writes once;
its `--json` envelope carries `changes` (one `{key, value}` per key, as stored),
and the top-level `key`/`value` only when a single pair was given.
- `--json` produces an `ok`-bearing envelope on stdout for every subcommand,
failures included, with three exceptions — none of which an agent should call.
`gitpic auth login --json` is the one command whose `--json` is a **stream**: one
complete JSON object per line, each tagged with `event`, the last line always `done` or
`error`. Parsing its stdout as a single object fails on the first line, and only a
human can type the one-time code anyway — hand the bare `gitpic auth login` to the user
and then read `gitpic auth status --json`. `gitpic completion <shell>` ignores `--json`
and prints the raw shell script. `gitpic config edit` **refuses** `--json` as `USAGE`:
it hands stdout to an editor, so it can never be one JSON document. Never call it —
use `gitpic config get --json` to read and `gitpic config set` to write.
- Only access the clipboard when the user explicitly requests it.
- Use absolute file paths.
- Never print the GitHub token in the conversation.
- Prefer `--link cdn` (default) unless the user asks for raw GitHub links. A
freshly uploaded file can take a moment to appear on jsDelivr; `raw_url` in the
same result is served by GitHub immediately.
- A cdn link cannot express a branch containing `/` (jsDelivr encodes the ref as
`repo@branch/path`, so the boundary becomes ambiguous). When `github.branch` has
a `/` and the link kind is cdn, the upload is refused with `USAGE` (2) **before
anything is committed** — retry with `--link raw`, which puts the branch in its
own path segment and works.
Wersje
W bazie nie ma innych skilli o nazwie gitpic.
Migawka bazy z 13.11.2026 · wersja paczki 0d0821436518 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100github-figure-bed
Wgrywa obrazy do dowolnego repozytorium GitHub jako hosting grafik i zwraca linki CDN lub markdown (jsdelivr, raw), z jednorazową konfiguracją przez setup.sh. - 96huashu-image-upload
Generuje ilustracje do artykułu, wgrywa je do hostingu obrazów i wstawia linki w formacie Markdown. - 100file-upload
Wysyła plik, na przykład raport HTML albo zrzut ekranu, przez CLI fileslop i zwraca publiczny link do udostępnienia. - 100upload-github-attachment
Wysyła lokalny obraz lub plik do załączników GitHuba i zwraca adres do osadzenia w issue, pull requeście lub komentarzu. - 100pic-upload
Wysyła lokalne pliki obrazów na hosting przez PicGo Server i zwraca stałe adresy CDN, na przykład dla zrzutów ekranu lub wygenerowanych obrazów. - 100github-image-upload
Wgrywa lokalne obrazy i pliki (PDF, zip, logi) na GitHub i osadza je w opisie PR, issue lub komentarzu jako linki user-attachments.