Comprime imágenes con un solo comando.
El mismo motor que la web, en tu terminal, tu build y tu agente. Node 20 o superior, sin telemetría, y las imágenes se eliminan en cuanto se comprimen.
+70Deja que tu agente la instale
Envía esto a Claude Code, Codex o cualquier agente de código: lee este documento y se configura solo.
Instálame la CLI de pipic siguiendo este documento y luego dime cómo iniciar sesión: https://pipic.cc/cliPor qué la CLI
Salida pensada para agentes
NDJSON y códigos de salida estables sobre los que un agente puede ramificar, no prosa que tenga que adivinar.
Una carpeta entera, un comando
En el sitio o en un directorio nuevo — lo mismo para lotes locales que para la salida del build.
Inicia sesión una vez
Después, scripts, CI (con PIPIC_TOKEN) y agentes funcionan solos: no hay nada más que aprobar.
Seguro por defecto
No toca nada sin un --replace o un -o explícito, las escrituras son atómicas y los archivos que no encogerían se dejan tal cual.
Primeros pasos
agentes · instala la skillInstala la skill una vez y tu agente encontrará pipic por su cuenta: nunca tendrás que nombrar la herramienta ni repetir las opciones.
Instala la CLI
Node 20 o superiorInstala la skill
Claude Code, Codex, Cursor y unos setenta másAprueba el inicio de sesión
Una aprobación por máquinaY luego solo pídelo
Sin nombre de herramienta ni opciones- Nunca ejecutar pipic login por su cuenta: la aprobación es cosa del usuario.
- skipped no es un fallo: viene con el motivo, por ejemplo que ya era bastante pequeña.
- Tras un fallo parcial, reejecutar solo los archivos fallidos: repetirlo todo gasta la cuota dos veces.
Para una tarea puntual, o un agente sin skills: dale el comando directamente. El contrato completo está en la sección siguiente:
Use the pipic CLI to compress the images in ./assets, replacing them in place: pipic ./assets --replace --json Run `pipic -h` for more.
¿El agente corre en un contenedor o sandbox que no ve tu ~/.config? Crea un token en tu página de cuenta y define PIPIC_TOKEN en ese entorno.
Ejecutarla tú mismo
personas · scripts · CIInstalación
Node 20 o superiorSin instalar nada
npxSin navegador — SSH, contenedores
device codeCI y sandboxes
PIPIC_TOKENComandos
pipic <rutas…>Comprime archivos o un directorio. Es el comando predeterminado.pipic login [--no-browser]Autoriza esta máquina mediante el navegador o con un código de dispositivo.pipic logoutCierra la sesión y revoca el token de esta máquina.pipic whoamiMuestra la cuenta con la que has iniciado sesión y su plan.pipic quotaMuestra cuánta cuota te queda este mes.pipic token listLista tus tokens con su prefijo y último uso.pipic token createImprime un enlace para crear uno en el sitio web — por seguridad, crear un token siempre ocurre ahí, nunca en la CLI.pipic token revoke <id>Revoca un token tuyo, normalmente efectivo en menos de un minuto.login, logout, whoami, quota y token se reconocen como subcomandos antes de tratarse como rutas. Para comprimir una carpeta que comparta uno de esos nombres, escribe ./login o login/ — cualquier ruta con un separador de directorio llega al comando de compresión en su lugar.
Opciones de compresión
--replaceSobrescribe los originales en el sitio — reemplazo atómico, permisos conservados, symlinks resueltos.
-o, --out <dir>Escribe los resultados en este directorio en su lugar.
--jsonSalida NDJSON, una línea por archivo — para scripts y agentes.
--concurrency <n>Subidas en paralelo. El valor por defecto es 4.
Debes indicar exactamente una de --replace o -o — son mutuamente excluyentes y ninguna es la opción por defecto. Sin ninguna de las dos, pipic termina con un error de uso (código 2).
Cosas que conviene saber
- Los archivos solo se reescriben cuando el resultado es realmente más pequeño — las imágenes ya optimizadas se omiten, indicando el motivo. Con -o el original se copia igualmente, así que el directorio de salida siempre es un conjunto completo.
- --replace escribe en un archivo temporal y luego lo renombra, así que un Ctrl-C nunca deja un archivo a medio escribir.
- Los archivos de más de 8 MB se omiten con un motivo claro, nunca se descartan en silencio.
- Se admiten JPG, PNG, WebP y AVIF. Nunca se envía telemetría.
- Con -o, dos archivos que comparten nombre —de subcarpetas distintas, por ejemplo— colisionan: pipic reporta un error para ambos en lugar de adivinar cuál conservar.
Contrato de salida JSON
--json imprime un objeto JSON por línea, uno por archivo, con seis campos fijos:
fileLa ruta que indicaste, sin cambios.status"ok", "skipped" o "error" — ningún otro valor.beforeTamaño original en bytes.afterTamaño comprimido en bytes — 0 en filas skipped/error.savedBytes ahorrados (before menos after) — nunca un porcentaje.errorPresente solo en filas skipped y error — un motivo legible, no un código.Códigos de salida
Es un contrato estable: haz que tus scripts y agentes ramifiquen según status y el código de salida — nunca según el texto de error.
API HTTP
¿Sin Node? Llama directamente al mismo motor de compresión por HTTP — una imagen por solicitud, sin SDK ni formularios multipart.
AuthorizationBearer <token> — obligatorio en cada solicitud.Content-Typeimage/png, image/jpeg, image/webp o image/avif — obligatorio, y debe coincidir con los bytes que envías.X-Original-NameOpcional. Codifícalo con URL primero — solo se devuelven los caracteres válidos para encodeURIComponent.BodyLos bytes crudos de la imagen, no multipart/form-data. Una imagen por solicitud, hasta 8 MB.Respuesta
200 OK devuelve la imagen comprimida como cuerpo de la respuesta — mismo formato de entrada y salida. Content-Type refleja el formato comprimido; Content-Length y X-Original-Name también llegan cuando están disponibles.
Consigue un token
La API usa los mismos Personal Access Tokens que la CLI. Inicia sesión con GitHub o Google y crea uno desde tu página de cuenta — el token en texto plano solo se muestra una vez, guárdalo en un lugar seguro.
Errores
Cualquier respuesta distinta de 200 devuelve este sobre JSON de error. Decide en tu código según el campo code, no según el texto de message — aquí tienes un ejemplo real:
400INVALID_TYPE — falta el Content-Type o no es de imagen; NO_FILE — el cuerpo está vacío401UNAUTHORIZED, TOKEN_EXPIRED o TOKEN_REVOKED — inicia sesión de nuevo o crea un token nuevo413FILE_TOO_LARGE — supera los 8 MB415UNSUPPORTED_TYPE — un tipo image/* que no comprimimos (solo PNG, JPEG, WebP, AVIF)429RATE_LIMITED (mira la cabecera Retry-After) o MONTHLY_QUOTA_EXCEEDED — se agotó la cuota de este mes502UPSTREAM_ERROR — nuestro backend rechazó esta imagen; reintentar los mismos bytes falla igual. El intento se devuelve a tu cuota503UPSTREAM_ERROR o ALL_KEYS_EXHAUSTED — sin capacidad temporalmente; puedes reintentar con backoff. El intento se devuelve a tu cuotaCosas que conviene saber
- Una solicitud cuenta para tu cuota en cuanto la aceptamos para comprimir — incluidas las que después fallan con 400, 413 o 415. Las rechazadas antes de ese punto nunca cuentan: cualquier 401, un 429 RATE_LIMITED y un archivo rechazado solo por su cabecera Content-Length declarada. Si el fallo es nuestro (502/503), ese intento se reembolsa automáticamente.
Todas las cabeceras y códigos de error, en un solo archivo legible por máquina: /openapi.json
Preguntas frecuentes
¿Puede un agente tocar archivos que no le pedí?
No — pipic exige indicar explícitamente --replace o -o <dir>. Sin ninguno de los dos se niega a ejecutarse, y nunca envía ni una sola solicitud antes de reportar ese error.
Inicié sesión una vez, ¿un agente puede seguir usando pipic para siempre?
Sí. La credencial vive en esta máquina, en ~/.config/pipic/config.json, y cualquier herramienta que se ejecute como tú puede leerla — no hace falta aprobar cada agente por separado.
Un agente dice que no ha iniciado sesión, ¿qué hago?
Lo más probable es que esté en un contenedor o sandbox que no ve tu ~/.config. Crea un token en tu página de cuenta y configúralo como PIPIC_TOKEN en ese entorno.
¿Qué pasa cuando se agota la cuota gratuita?
pipic termina con el código 4 y nunca se cobra nada automáticamente. Free incluye 100 imágenes al mes; Pro lo eleva a 5.000.
¿Se guardan mis imágenes en algún sitio?
No — se eliminan del servidor en cuanto termina la compresión, y nada se almacena a largo plazo.