PiPic
Anmelden

Bilder mit einem einzigen Befehl komprimieren — im Terminal, im Build oder in deinem Agenten.

Die PiPic-CLI bringt dieselbe Komprimierung wie die Website in Skripte, CI-Pipelines und KI-Coding-Agenten. Node 20 oder neuer erforderlich. Keine Telemetrie. Bilder werden gelöscht, sobald sie komprimiert sind.

$ pipic ./assets --replace
✓ 38 images compressed — 24.1 MB → 5.8 MB (−76%)
3 already optimized, left unchanged

Quellcode: GitHub · npm

Warum pipic CLI?

  • Agentenfreundlich von Grund auf: NDJSON-Ausgabe und stabile Exit-Codes, die ein KI-Agent direkt parsen und zum Verzweigen nutzen kann, statt Fließtext zu deuten.
  • Ein Befehl komprimiert einen ganzen Ordner — an Ort und Stelle oder in ein neues Verzeichnis — für lokale Stapel genauso wie für Build-Artefakte.
  • Einmal anmelden, danach läuft es unbeaufsichtigt: Skripte, CI (über PIPIC_TOKEN) und Agenten nutzen es alle, ohne noch einmal etwas bestätigen zu müssen.
  • Nie Telemetrie. Bilder werden in dem Moment vom Server gelöscht, in dem die Komprimierung fertig ist.

Voraussetzungen

Node 20 oder neuer erforderlich. Der Befehl heißt pipic.

Schnellstart (Mensch)

Einmalig

pipic login öffnet deinen Browser, um die Anfrage zu bestätigen. Nach der Bestätigung werden die Anmeldedaten auf diesem Rechner gespeichert — jedes Tool, das als du läuft, einschließlich eines KI-Coding-Agenten, kann pipic danach ohne erneute Anmeldung nutzen.

$ npm i -g @pipic/cli
$ pipic login
Opening your browser…
✓ Signed in as you@example.com

Kein Browser? SSH, Container, CI

pipic login --no-browser — oder eine Umgebung, die die CLI als headless erkennt (SSH, CI, ein Container) — weicht auf einen Gerätecode aus, den du von jedem anderen Gerät mit Browser bestätigst.

$ pipic login --no-browser
Open https://pipic.cc/cli/authorize
Enter this code: PXBQ-GTZM
Expires in 10 minutes · waiting…

Schnellstart (KI-Agent)

Jedes Mal

Auf diesem Rechner schon installiert und angemeldet? Füge das hier unverändert in deinen Coding-Agenten ein:

Use the `pipic` CLI to compress the images in ./assets.
It's already installed and signed in — do not install it or run
`pipic login` yourself.

  pipic ./assets --replace --json

It prints one JSON object per file:
  {"file":"a.png","status":"ok","before":102400,"after":41000,"saved":61400}
status is "ok", "skipped" or "error". "skipped" is not a failure — it
carries an `error` string explaining why (e.g. already small enough).

Exit 0 = all good, 1 = some files failed, 3 = not signed in,
4 = monthly quota exhausted.
Don't retry on exit 2 (usage error), 3 or 4 — on 3, stop and tell the
user to sign in. On exit 1, re-run only the paths whose rows had status
"error": a full re-run re-uploads every file and spends quota again.

Läuft der Agent in einem Container oder einer Sandbox ohne Zugriff auf dein ~/.config? Erstelle ein Token auf deiner Kontoseite und setze es dort als PIPIC_TOKEN.

Befehle

pipic <Pfade…>Dateien oder ein Verzeichnis komprimieren. Das ist der Standardbefehl.
pipic login [--no-browser]Diesen Rechner per Browser oder mit einem Gerätecode autorisieren.
pipic logoutAbmelden und das Token dieses Rechners widerrufen.
pipic whoamiDas angemeldete Konto und den Tarif anzeigen.
pipic quotaZeigen, wie viel Kontingent diesen Monat noch übrig ist.
pipic token listTokens mit Präfix und letzter Nutzung auflisten.
pipic token createGibt einen Link aus, um eines auf der Website zu erstellen — aus Sicherheitsgründen passiert das Erstellen eines Tokens immer dort, nie in der CLI.
pipic token revoke <id>Ein eigenes Token widerrufen, meist innerhalb einer Minute wirksam.

login, logout, whoami, quota und token werden zuerst als Unterbefehle erkannt, bevor sie als Pfade behandelt werden. Um einen Ordner mit einem dieser Namen zu komprimieren, schreibe ./login oder login/ — alles mit einem Pfadtrennzeichen geht stattdessen an den Komprimierungsbefehl.

Komprimierungsoptionen

--replaceOriginale an Ort und Stelle überschreiben — atomarer Austausch, Rechte bleiben erhalten, Symlinks werden aufgelöst.
-o, --out <Verzeichnis>Ergebnisse stattdessen in dieses Verzeichnis schreiben.
--jsonNDJSON-Ausgabe, eine Zeile pro Datei — für Skripte und Agenten.
--concurrency <n>Parallele Uploads. Standard ist 4.

Du musst genau eines von --replace oder -o angeben — beide schließen sich gegenseitig aus, keins ist die Voreinstellung. Ohne eines von beiden bricht pipic mit einem Nutzungsfehler ab (Exit-Code 2).

Gut zu wissen

  • Dateien werden nur zurückgeschrieben, wenn das Ergebnis wirklich kleiner ist — bereits optimierte Bilder werden übersprungen, mit Angabe des Grunds. Bei -o wird das Original trotzdem mitkopiert, sodass das Ausgabeverzeichnis immer vollständig ist.
  • --replace schreibt in eine temporäre Datei und benennt sie dann um, sodass ein Ctrl-C nie eine halb geschriebene Datei hinterlässt.
  • Dateien über 8 MB werden mit klarem Grund übersprungen, nie stillschweigend verworfen.
  • JPG, PNG, WebP und AVIF werden unterstützt. Es wird nie Telemetrie gesendet.
  • Bei -o kollidieren zwei gleichnamige Dateien aus unterschiedlichen Unterordnern: pipic meldet für beide einen Fehler, statt zu raten, welche behalten werden soll.

JSON-Ausgabevertrag

--json gibt pro Datei eine Zeile mit einem JSON-Objekt aus, mit sechs festen Feldern:

pipic ./assets --json --replace
{"file":"/p/hero.png","status":"ok","before":2411233,"after":486201,"saved":1925032}
{"file":"/p/notes.txt","status":"skipped","before":0,"after":0,"saved":0,"error":"unsupported file type"}
fileDer übergebene Pfad, unverändert.
status"ok", "skipped" oder "error" — keine anderen Werte.
beforeUrsprüngliche Größe in Bytes.
afterKomprimierte Größe in Bytes — 0 bei skipped/error-Zeilen.
savedEingesparte Bytes (before minus after) — nie ein Prozentwert.
errorNur bei skipped- und error-Zeilen vorhanden — ein für Menschen lesbarer Grund, kein Code.

Exit-Codes

0Alle Dateien erfolgreich
1Einige Dateien fehlgeschlagen
2Nutzungsfehler
3Anmeldung erforderlich
4Kontingent aufgebraucht

Das ist ein stabiler Vertrag: Skripte und Agenten sollten nach status und dem Exit-Code verzweigen — nie nach dem Text von error.

HTTP-API

Kein Node zur Hand? Ruf dieselbe Komprimierungs-Engine direkt per HTTP auf — ein Bild pro Anfrage, kein SDK, keine multipart-Formulare.

POST https://pipic.cc/compress/image

Token holen

Die API nutzt dieselben Personal Access Tokens wie die CLI. Melde dich mit GitHub oder Google an und erstelle eines auf deiner Kontoseite — das Klartext-Token wird nur einmal angezeigt, also sicher aufbewahren.

Token erstellen

Anfrage

AuthorizationBearer <token> — bei jeder Anfrage erforderlich.
Content-Typeimage/png, image/jpeg, image/webp oder image/avif — erforderlich und muss zu den gesendeten Bytes passen.
X-Original-NameOptional. Erst URL-kodieren — in der Antwort kommen nur die für encodeURIComponent zulässigen Zeichen zurück.
BodyRohe Bilddaten, kein multipart/form-data. Ein Bild pro Anfrage, bis zu 8 MB.
curl
$ curl -X POST https://pipic.cc/compress/image \
  -H "Authorization: Bearer $PIPIC_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png \
  -o photo-compressed.png

Antwort

200 OK liefert das komprimierte Bild als Antwortkörper — gleiches Format rein, gleiches Format raus. Content-Type spiegelt das komprimierte Format; Content-Length und X-Original-Name kommen mit, wenn verfügbar.

Fehler

Jede Antwort außer 200 liefert diesen JSON-Fehlerumschlag. Werte in deinem Code das Feld code aus, nicht den message-Text — hier ein echtes Beispiel:

{"success":false,"code":"MONTHLY_QUOTA_EXCEEDED","message":"Monthly compression quota reached, try again next month"}
400INVALID_TYPE — Content-Type fehlt oder ist kein Bildtyp; NO_FILE — Body ist leer
401UNAUTHORIZED, TOKEN_EXPIRED oder TOKEN_REVOKED — erneut anmelden oder neues Token erstellen
413FILE_TOO_LARGE — über 8 MB
415UNSUPPORTED_TYPE — ein image/*-Typ, den wir nicht komprimieren (nur PNG, JPEG, WebP, AVIF)
429RATE_LIMITED (siehe Retry-After-Header) oder MONTHLY_QUOTA_EXCEEDED — Kontingent für diesen Monat aufgebraucht
502UPSTREAM_ERROR — unser Backend hat dieses Bild abgelehnt; dieselben Bytes erneut zu senden schlägt genauso fehl. Der Versuch wird deinem Kontingent gutgeschrieben
503UPSTREAM_ERROR oder ALL_KEYS_EXHAUSTED — vorübergehend keine Kapazität; erneuter Versuch mit Backoff ist möglich. Der Versuch wird deinem Kontingent gutgeschrieben

Gut zu wissen

  • Eine Anfrage zählt gegen dein Kontingent, sobald wir sie zur Komprimierung annehmen — auch wenn sie anschließend mit 400, 413 oder 415 fehlschlägt. Vorher abgelehnte Anfragen zählen nie: jedes 401, ein 429 RATE_LIMITED und eine Datei, die allein wegen ihres deklarierten Content-Length-Headers abgelehnt wird. Scheitern wir auf unserer Seite (502/503), wird dieser Versuch automatisch zurückerstattet.

Jeder Header und jeder Fehlercode, maschinenlesbar in einer Datei: /openapi.json

FAQ

Rührt ein Agent Dateien an, die ich nicht angegeben habe?

Nein — pipic verlangt ein explizites --replace oder -o <Verzeichnis>. Ohne eines von beiden verweigert es die Ausführung, und es wird nie auch nur eine Anfrage gesendet, bevor dieser Fehler gemeldet wird.

Ich habe mich einmal angemeldet — kann ein Agent pipic danach dauerhaft nutzen?

Ja. Die Anmeldedaten liegen auf diesem Rechner unter ~/.config/pipic/config.json, und jedes Tool, das als du läuft, kann sie lesen — für jeden Agenten ist keine zusätzliche Freigabe nötig.

Ein Agent meldet, er sei nicht angemeldet — was tun?

Er läuft höchstwahrscheinlich in einem Container oder einer Sandbox ohne Zugriff auf dein ~/.config. Erstelle ein Token auf deiner Kontoseite und setze es dort als PIPIC_TOKEN.

Was passiert, wenn das kostenlose Kontingent aufgebraucht ist?

pipic beendet sich mit Exit-Code 4, es wird nie automatisch etwas abgerechnet. Free umfasst 100 Bilder pro Monat, Pro erhöht das auf 5.000.

Werden meine Bilder irgendwo gespeichert?

Nein — sie werden in dem Moment vom Server gelöscht, in dem die Komprimierung fertig ist, und nichts wird langfristig aufbewahrt.

Datenschutz

Nie Telemetrie. Bilder werden in dem Moment vom Server gelöscht, in dem die Komprimierung fertig ist — nichts wird langfristig gespeichert.

Vollständige Datenschutzerklärung lesen