pikcloud/skills – CLI para almacenamiento en la nube PikPak

Skill de operación CLI de PikPak

Opera el almacenamiento en la nube PikPak a través de la herramienta de línea de comandos pikpak.

Instalar pikpak

Elige un método de instalación según tu sistema operativo:

macOS / Linux:

curl -fsSL https://download.mypikpak.com/cli/install.sh | bash

Windows (PowerShell):

irm https://download.mypikpak.com/cli/install.ps1 | iex

Homebrew:

brew install pikcloud/tap/pikpak-cli

Después de la instalación, ejecuta pikpak version para verificar.

Con un código de invitación — el instalador lo guarda para el próximo pikpak auth register en esta máquina, sin contactar la API de invitación:

curl -fsSL https://download.mypikpak.com/cli/install.sh | bash -s -- --affiliate <código>
$env:PIKPAK_AFFILIATE="<código>"; irm https://download.mypikpak.com/cli/install.ps1 | iex
brew install pikcloud/tap/pikpak-cli && pikpak auth register --affiliate <código>

Los instaladores guardan el código en un archivo affiliate de texto plano separado; no se necesita ningún analizador Python o JSON, y settings.json nunca se lee ni modifica. Si falla la escritura se advierte pero no falla la instalación ni sobrescribe el código anterior. En ese caso, pasa el código con pikpak auth register --affiliate <código>.

pikpak skill install escribe este documento en el directorio de skills de cada agente de codificación de IA en la máquina (Claude Code, Codex, Gemini CLI, opencode, Cursor, goose, iFlow, Qwen Code, ...). Ejecútalo después de pikpak update si este documento alguna vez difiere del binario instalado; pikpak skill ls muestra dónde está instalado y si está actualizado.

Variables de Entorno

Variable	Descripción	Valor por Defecto
PIKPAK_DIR	Directorio de credenciales	~/.pikpak
PIKPAK_CREDENTIALS	Ruta completa al archivo de credenciales OAuth	~/.pikpak/.credentials.json
PIKPAK_TOKEN	Token de acceso personal; tiene prioridad sobre cualquier credencial guardada	sin establecer
PIKPAK_PAT_PATH	Ruta completa al archivo PAT guardado por auth token	~/.pikpak/.pat.json
PIKPAK_VERSION	Versión especificada durante la instalación	Última
PIKPAK_INSTALL_DIR	Directorio de instalación	~/.local/bin (macOS/Linux), %USERPROFILE%\.pikpak (Windows)
PIKPAK_NO_UPDATE_NOTIFIER	Establecer a 1 para deshabilitar comprobaciones y recordatorios automáticos de actualización; version --check y update explícitos siguen funcionando	sin establecer
PIKPAK_NO_LOG	Establecer a cualquier valor no vacío (ej. 1) para anular config log y no registrar el registro de diagnóstico	sin establecer
PIKPAK_NO_SKILL_SYNC	Establecer a cualquier valor no vacío para evitar que pikpak update refresque los skills de agente instalados	sin establecer
PIKPAK_AFFILIATE	Código de invitación leído por install.sh / install.ps1 en el momento de la instalación (el CLI en sí no lo lee)	sin establecer

Prioridad de credenciales: PIKPAK_TOKEN → PAT guardado por pikpak auth token → credenciales OAuth de pikpak auth login.

Identidad del dispositivo: el CLI mantiene un ID de dispositivo estable por instalación en ~/.pikpak/.device.json (X-Device-Id). Se reutiliza para cada método de inicio de sesión y sobrevive a la rotación de tokens y auth logout; eliminarlo hace que la máquina parezca un dispositivo nuevo para el control de riesgos de PikPak.

Autenticación

La mayoría de los comandos requieren iniciar sesión primero. Las credenciales se almacenan en ~/.pikpak/.credentials.json.

pikpak auth login                                    # Detecta automáticamente el método de inicio de sesión (navegador si está disponible, flujo de dispositivo en caso contrario)
pikpak auth login -m browser                         # Inicio de sesión OAuth por navegador (abre el navegador, 30s sin respuesta -> cae en flujo de dispositivo)
pikpak auth login -m browser --no-launch-browser     # Inicio de sesión OAuth por navegador (imprime URL, sin apertura automática)
pikpak auth login -m device                          # Flujo de dispositivo (código QR + URL de verificación + sondeo automático)
pikpak auth login -m device -F json                  # Flujo de dispositivo: muestra información de autenticación como JSON y sale (sin sondeo, para IA)
pikpak auth login --continue <device_code>           # Sondea el estado del código de dispositivo una vez y sale (usar con -F json)
pikpak auth login --force                            # Vuelve a iniciar sesión incluso si ya está autenticado
pikpak auth login -l "mi-sesión"                      # Establecer una etiqueta de sesión personalizada
pikpak auth login --scope files:manage,cloud_download # Preseleccionar alcances OAuth (separados por comas)

pikpak auth register                                 # Registrar una nueva cuenta (mismos flujos de navegador/dispositivo que login)
pikpak auth register --affiliate <código>              # Registrar con un código de afiliado/invitación
pikpak auth register --affiliate=                    # Omitir el código guardado del instalador para este registro
pikpak auth register -m device                       # Forzar flujo de dispositivo para el registro

pikpak auth token <token>                            # Guardar un token de acceso personal para uso no interactivo
pikpak auth logout                                   # Limpiar la sesión local; funciona sin conexión y con credenciales rotas/expiradas (no puede eliminar PIKPAK_TOKEN del entorno)
pikpak auth status                                   # Estado de inicio de sesión + panel de cuenta: identidad, VIP, cuota de almacenamiento (añadir -F json para scripts)

Identificadores --scope compatibles: files:read, files:write, files:manage, files:purge, cloud_download, share, invite, account. Omitir --scope no envía ningún alcance y deja que el servidor de autorización aplique sus valores predeterminados.

Guía de inicio de sesión para agente de IA: El inicio de sesión con contraseña ya no es compatible. Para entornos no interactivos/de IA, usa el Flujo de Dispositivo:

1. Ejecuta pikpak auth login -m device -F json para obtener device_code, verification_uri, user_code, expires_in, interval
2. Muestra al usuario la URL de verificación y el código (o código QR)
3. Sondea con pikpak auth login --continue <device_code> -F json hasta que status sea success

Si el entorno admite un navegador (macOS/Linux con interfaz gráfica), pikpak auth login (detección automática) o pikpak auth login -m browser funciona sin ninguna bandera. El inicio de sesión verifica las credenciales existentes primero; usa --force para crear una nueva sesión.

Alternativa completamente no interactiva: pikpak auth token <PAT>, o exporta PIKPAK_TOKEN=<PAT>.

Advertencia de registro: pikpak auth register -F json imprime signup_uri, handoff_code, qr_png_path, expires_in (y affiliate siempre que haya un código en juego — bandera o registrado) y sale — no devuelve un device_code, por lo que no se puede sondear con --continue. Para registros impulsados por IA, ejecuta pikpak auth register sin -F (sondea interactivamente), o haz que el usuario se registre en el navegador y luego use pikpak auth login.

Referencia de Comandos

Navegación de Archivos

El ID del directorio raíz es una cadena vacía "", no / o /root.

pikpak ls                    # Listar directorio raíz
pikpak ls <folderID>         # Listar carpeta especificada (posicional)
pikpak ls -p <folderID>      # Lo mismo, mediante bandera (el argumento posicional gana si se dan ambos)
pikpak ls --type file        # Mostrar solo archivos (filtro de tipo del lado del servidor, funciona también con --raw)
pikpak ls --type folder      # Mostrar solo carpetas (filtro de tipo del lado del servidor, funciona también con --raw)
pikpak ls -l 50              # Elementos por página (--limit, por defecto 100; el servidor redondea valores inferiores a 10)
pikpak ls -t <token>         # Paginación (--token, de la salida de ls anterior)
pikpak ls -F json            # Salida JSON (preferida para IA: id, parent_id, name, kind, size, mime_type, file_category, modified, hash; mime_type/file_category se omiten para carpetas y para archivos que el servicio no clasificó)
pikpak ls --raw              # JSON de la API sin modificar para todo el listado: añade params.duration/width/height, params.url, audit, thumbnail_link, spell_name, apps; tamaño en bytes

Solo se listan archivos no eliminados y completamente procesados. Un ls es una página: lee next_page_token de la salida y pásalo de vuelta con -t para continuar. -l es una solicitud de tamaño de página, no un límite estricto — el servicio devuelve 10 elementos para cualquier valor menor, y una página también puede devolver menos de -l cuando la carpeta termina.

Búsqueda de Archivos (no disponible)

El comando search está deshabilitado en esta versión porque la API de búsqueda del lado del servidor no está disponible. No sugieras ni ejecutes pikpak search; localiza archivos recorriendo carpetas con pikpak ls (opcionalmente -F json).

Detalles de Archivos

pikpak get <fileID>                      # Información básica
pikpak get <fileID> --url-type download  # Incluir URL de descarga
pikpak get <fileID> --url-type play      # Incluir URL de reproducción
pikpak get <fileID> --url-type all       # Incluir todas las URLs
pikpak get <fileID> --raw                # JSON de la API sin modificar (usage=ALL; url_type ignorado)

Campos de get -F json: id, name, type (file/folder), size, mime, hash, created, modified, phase, más download_url, play_url, play_resolution cuando --url-type los solicita. Nota que los nombres difieren de ls: type/mime aquí versus kind/mime_type allí. Las URLs solo se devuelven para archivos — --url-type en una carpeta produce solo metadatos.

--raw omite completamente esta forma reducida — consulta Salida API sin modificar (--raw) más abajo.

Salida API sin modificar (--raw)

pikpak ls --raw y pikpak get <fileID> --raw imprimen el cuerpo de respuesta de la API de PikPak textualmente (solo re-identado). Úsalos siempre que el campo que necesitas no esté en las formas reducidas de ls / get.

pikpak ls --raw                                  # Listado completo, todos los campos que devuelve la API
pikpak ls --raw -p <folderID> -l 500             # Mismos filtros/banderas de paginación que ls simple
pikpak get <fileID> --raw                        # Un archivo, usage=ALL
pikpak ls --raw -F yaml                          # Mismo cuerpo convertido a YAML

Qué añade --raw (por archivo, más allá de los 9 campos de ls -F json):

Campo sin procesar	Significado	Por qué importa
params.duration	Duración de reproducción en segundos, como cadena ("1420")	La única fuente de duración de vídeo — ausente tanto en ls como en la salida predeterminada de get
params.width / params.height	Dimensiones en píxeles, como cadenas ("1920" / "1080")	Filtrado por resolución; get --url-type play solo da una etiqueta como 1080p
params.url	De dónde vino el archivo: magnet:?xt=urn:btih:… para torrents, una URL http(s) para descargas de enlaces	El único registro de una fuente de descarga sin conexión
params.task_id	ID de la tarea sin conexión que produjo el archivo	Vincula un archivo con pikpak task get <taskID>
params.db_modify_time, params.platform, params.platform_icon, params.original_share_id	Metadatos del lado del servidor, presentes en cada elemento	Procedencia
size	Bytes sin procesar como cadena ("392927574")	Los formatos de salida predeterminados lo formatean (375 MB) y no se puede comparar numéricamente
created_time / modified_time / user_modified_time	RFC3339 con desplazamiento	La salida predeterminada es texto local truncado YYYY-MM-DD HH:MM
medias[]	Array completo: media_id, media_name, resolution_name, link.url, video.{width,height,duration,bit_rate,frame_rate,video_codec,audio_codec,hdr_type}, audio.{artist,album,sample_rate,…}	Cada variante reproducible más metadatos reales de códec/HDR, no solo el que play elige
audit	{status, message, title}	Detectar recursos bloqueados/en revisión
apps, spell_name, tags, reference_events, thumbnail_link, icon_link, web_content_link, phase, starred, trashed, writable, folder_type, revision, user_id	Campos restantes de la API	Cualquier cosa que la forma reducida omita, incluidos campos añadidos por futuras versiones de la API

Semántica — léelo antes de usarlo:

• Textual. El cuerpo no se re-codifica: el orden de los campos es el de la API, y & en enlaces firmados permanece como un & literal (nunca \u0026). Seguro para alimentar directamente a jq.
• Siempre estructurado. --raw implica salida JSON incluso sin -F; -F yaml convierte el mismo cuerpo. No hay tabla legible por humanos en este modo.
• ls --raw es una solicitud por página, no por archivo. Mismas banderas -p / -l / -t / --type y los mismos filtros del lado del servidor (no eliminados, PHASE_TYPE_COMPLETE) que ls simple. La paginación es la misma: lee next_page_token del cuerpo sin procesar y pásalo de vuelta con -t. Aumenta -l (ej. -l 500) para cubrir una carpeta grande en una sola llamada en lugar de hacer un bucle de get.
• --type se combina con --raw. Es un filtro de kind del lado del servidor (drive#file / drive#folder), por lo que el cuerpo pasado ya contiene solo el tipo solicitado y una página aún contiene hasta -l elementos. Ya no es necesario filtrar del lado del cliente con jq en .files[] | select(.kind == …).
• get --raw siempre solicita usage=ALL — la respuesta más completa — por lo que --url-type se ignora y ya no es necesario: medias[].link.url y web_content_link ya están en el cuerpo. También omite la sonda de actividad de la URL de descarga, por lo que sigue siendo una única solicitud de lectura y nunca añade las claves derivadas download_url / play_url / play_resolution.
• Los nombres difieren de las formas reducidas. Sin procesar usa las claves propias de la API: kind es drive#file / drive#folder (no file / folder), modified_time (no modified), starred (no star).
• La presencia del campo no está garantizada. params está ausente o es parcial para carpetas y archivos no multimedia; medias suele ser [] hasta que el servidor termina la transcodificación. Protégete con select(.params.duration != null) o valores predeterminados // "0".
• No filtres la salida sin procesar por file_category, y no confíes en mime_type tampoco. La API omite con frecuencia file_category incluso para vídeos (la forma reducida ls -F json lo deriva), y mime_type vuelve como "" en una buena parte de los archivos multimedia, por lo que tanto select(.file_category == "video") como select(.mime_type | startswith("video")) eliminan silenciosamente vídeos reales. La prueba fiable de vídeo en la salida sin procesar es la presencia de params.duration.

Recetas:

# Vídeos de más de una hora (UNA llamada a la API — nunca hagas un bucle de `get` sobre una carpeta)
pikpak ls --raw | jq -r '.files[] | select((.params.duration // "0" | tonumber) > 3600)
  | "\(.name)\t\(.params.duration)s"'

# Archivos 4K, l

…

[truncado para traducción]