pikcloud/skills

Habilidade de Operação PikPak CLI

Opere o armazenamento em nuvem PikPak através da ferramenta de linha de comando pikpak.

Instalar o pikpak

Escolha o método de instalação de acordo com seu sistema operacional:

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

Após a instalação, execute pikpak version para verificar.

Com um código de convite de um convidador — o instalador o registra para o próximo pikpak auth register nesta máquina, sem contatar a API de convite:

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

Os instaladores salvam o código em um arquivo affiliate de texto simples separado; nenhum parser Python ou JSON é necessário, e settings.json nunca é lido ou modificado. Uma falha de gravação avisa, mas não falha na instalação nem sobrescreve o código anterior. Nesse caso, passe o código com pikpak auth register --affiliate <code>.

pikpak skill install escreve este documento no diretório de habilidades de todo agente de codificação de IA na máquina (Claude Code, Codex, Gemini CLI, opencode, Cursor, goose, iFlow, Qwen Code, ...). Execute-o após pikpak update se este documento alguma vez divergir do binário instalado; pikpak skill ls mostra onde ele está instalado e se está atualizado.

Variáveis de Ambiente

Variável	Descrição	Padrão
PIKPAK_DIR	Diretório de credenciais	~/.pikpak
PIKPAK_CREDENTIALS	Caminho completo para o arquivo de credenciais OAuth	~/.pikpak/.credentials.json
PIKPAK_TOKEN	Token de Acesso Pessoal; tem precedência sobre qualquer credencial salva	não definido
PIKPAK_PAT_PATH	Caminho completo para o arquivo PAT salvo por auth token	~/.pikpak/.pat.json
PIKPAK_VERSION	Versão especificada durante a instalação	Última
PIKPAK_INSTALL_DIR	Diretório de instalação	~/.local/bin (macOS/Linux), %USERPROFILE%\.pikpak (Windows)
PIKPAK_NO_UPDATE_NOTIFIER	Defina como 1 para desabilitar verificações e lembretes automáticos de atualização; version --check e update explícitos ainda funcionam	não definido
PIKPAK_NO_LOG	Defina para qualquer valor não vazio (ex.: 1) para sobrescrever config log e nunca registrar o log de diagnóstico	não definido
PIKPAK_NO_SKILL_SYNC	Defina para qualquer valor não vazio para impedir que pikpak update atualize as habilidades do agente instaladas	não definido
PIKPAK_AFFILIATE	Código de convite lido por install.sh / install.ps1 no momento da instalação (o próprio CLI não o lê)	não definido

Prioridade de credenciais: PIKPAK_TOKEN → PAT salvo por pikpak auth token → Credenciais OAuth de pikpak auth login.

Identidade do dispositivo: o CLI mantém um ID de dispositivo estável por instalação em ~/.pikpak/.device.json (X-Device-Id). Ele é reutilizado para cada método de login e sobrevive à rotação de tokens e auth logout; deletá-lo faz a máquina parecer um dispositivo novo para o controle de risco do PikPak.

Autenticação

A maioria dos comandos requer login primeiro. As credenciais são armazenadas em ~/.pikpak/.credentials.json.

pikpak auth login                                    # Detecta automaticamente o método de login (navegador se disponível, fluxo de dispositivo caso contrário)
pikpak auth login -m browser                         # Login OAuth via navegador (abre o navegador, 30s sem resposta -> volta para fluxo de dispositivo)
pikpak auth login -m browser --no-launch-browser     # Login OAuth via navegador (imprime URL, não abre automaticamente)
pikpak auth login -m device                          # Fluxo de dispositivo (QR code + URL de verificação + polling automático)
pikpak auth login -m device -F json                  # Fluxo de dispositivo: gera informações de autenticação como JSON e sai (sem polling, para IA)
pikpak auth login --continue <device_code>           # Verifica o status do código do dispositivo uma vez e sai (use com -F json)
pikpak auth login --force                            # Faz login novamente mesmo se já estiver autenticado
pikpak auth login -l "my-session"                    # Define um rótulo de sessão personalizado
pikpak auth login --scope files:manage,cloud_download # Pré-seleciona escopos OAuth (separados por vírgula)

pikpak auth register                                 # Registra uma nova conta (mesmos fluxos de navegador/dispositivo que o login)
pikpak auth register --affiliate <code>              # Registra com um código de afiliado/convite
pikpak auth register --affiliate=                    # Pula o código salvo pelo instalador para este registro
pikpak auth register -m device                       # Força o fluxo de dispositivo para registro

pikpak auth token <token>                            # Salva um Token de Acesso Pessoal para uso não interativo
pikpak auth logout                                   # Limpa a sessão local; funciona offline e com credenciais quebradas/expiradas (não pode remover PIKPAK_TOKEN do ambiente)
pikpak auth status                                   # Status de login + painel da conta: identidade, VIP, cota de armazenamento (adicione -F json para scripts)

Identificadores --scope suportados: files:read, files:write, files:manage, files:purge, cloud_download, share, invite, account. Omitir --scope não envia escopo e permite que o servidor de autorização aplique seus padrões.

Guia de login para Agente de IA: O login por senha não é mais suportado. Para ambientes não interativos/de IA, use o Fluxo de Dispositivo:

1. Execute pikpak auth login -m device -F json para obter device_code, verification_uri, user_code, expires_in, interval
2. Mostre ao usuário a URL de verificação e o código (ou QR code)
3. Faça polling com pikpak auth login --continue <device_code> -F json até que status seja success

Se o ambiente suportar um navegador (macOS/Linux com GUI), pikpak auth login (detecção automática) ou pikpak auth login -m browser funciona sem nenhuma flag. O login verifica as credenciais existentes primeiro; use --force para criar uma nova sessão.

Alternativa totalmente não interativa: pikpak auth token <PAT>, ou exporte PIKPAK_TOKEN=<PAT>.

Ressalva de registro: pikpak auth register -F json imprime signup_uri, handoff_code, qr_png_path, expires_in (e affiliate sempre que um código estiver em jogo — flag ou gravado) e sai — ele não retorna um device_code, portanto não pode ser verificado com --continue. Para registro orientado por IA, execute pikpak auth register sem -F (ele faz polling interativamente), ou peça ao usuário para registrar no navegador e depois use pikpak auth login.

Referência de Comandos

Navegação de Arquivos

O ID do diretório raiz é uma string vazia "", não / ou /root.

pikpak ls                    # Lista o diretório raiz
pikpak ls <folderID>         # Lista a pasta especificada (posicional)
pikpak ls -p <folderID>      # Mesmo, via flag (o argumento posicional vence se ambos forem fornecidos)
pikpak ls --type file        # Mostra apenas arquivos (filtro de tipo do servidor, funciona também com --raw)
pikpak ls --type folder      # Mostra apenas pastas (filtro de tipo do servidor, funciona também com --raw)
pikpak ls -l 50              # Itens por página (--limit, padrão 100; o servidor arredonda valores abaixo de 10 para 10)
pikpak ls -t <token>         # Paginação (--token, da saída anterior de ls)
pikpak ls -F json            # Saída JSON (preferida para IA: id, parent_id, name, kind, size, mime_type, file_category, modified, hash; mime_type/file_category são omitidos para pastas e para arquivos que o serviço não classificou)
pikpak ls --raw              # JSON da API não modificado para a listagem completa: adiciona params.duration/width/height, params.url, audit, thumbnail_link, spell_name, apps; size em bytes

Apenas arquivos não excluídos e totalmente processados são listados. Um ls é uma página: leia next_page_token da saída e passe de volta com -t para continuar. -l é uma solicitação de tamanho de página, não um limite máximo — o serviço retorna 10 itens para qualquer valor menor, e uma página também pode vir com menos itens que -l quando a pasta termina.

Pesquisa de Arquivos (indisponível)

O comando search está desabilitado nesta versão porque a API de pesquisa do lado do servidor está indisponível. Não sugira nem execute pikpak search; localize arquivos percorrendo pastas com pikpak ls (opcionalmente -F json).

Detalhes do Arquivo

pikpak get <fileID>                      # Informações básicas
pikpak get <fileID> --url-type download  # Inclui URL de download
pikpak get <fileID> --url-type play      # Inclui URL de reprodução
pikpak get <fileID> --url-type all       # Inclui todas as URLs
pikpak get <fileID> --raw                # JSON da API não modificado (usage=ALL; url_type ignorado)

Campos de get -F json: id, name, type (file/folder), size, mime, hash, created, modified, phase, mais download_url, play_url, play_resolution quando --url-type é solicitado. Observe que a nomenclatura difere de ls: type/mime aqui versus kind/mime_type lá. URLs são retornadas apenas para arquivos — --url-type em uma pasta retorna apenas metadados.

--raw ignora completamente esta forma reduzida — veja Saída Bruta da API abaixo.

Saída Bruta da API (--raw)

pikpak ls --raw e pikpak get <fileID> --raw imprimem o corpo da resposta da API de drive do PikPak literalmente (apenas re-indentado). Use-os sempre que o campo que você precisa não estiver nas formas reduzidas de ls / get acima.

pikpak ls --raw                                  # Listagem completa, todos os campos que a API retorna
pikpak ls --raw -p <folderID> -l 500             # Mesmos filtros/flags de paginação que ls simples
pikpak get <fileID> --raw                        # Um arquivo, usage=ALL
pikpak ls --raw -F yaml                          # Mesmo corpo convertido para YAML

O que --raw adiciona (por arquivo, além dos 9 campos de ls -F json):

Campo bruto	Significado	Por que importa
params.duration	Duração da reprodução em segundos, como uma string ("1420")	A única fonte de duração de vídeo — ausente tanto na saída padrão de ls quanto de get
params.width / params.height	Dimensões em pixels, como strings ("1920" / "1080")	Filtragem por resolução; get --url-type play fornece apenas um rótulo como 1080p
params.url	De onde o arquivo veio: magnet:?xt=urn:btih:… para torrents, uma URL http(s) para downloads de link	O único registro da origem de um download offline
params.task_id	ID da tarefa offline que produziu o arquivo	Liga um arquivo de volta a pikpak task get <taskID>
params.db_modify_time, params.platform, params.platform_icon, params.original_share_id	Metadados do lado do serviço, presentes em todos os itens	Proveniência
size	Bytes brutos como uma string ("392927574")	Os formatos de saída padrão o formatam (375 MB) e não podem ser comparados numericamente
created_time / modified_time / user_modified_time	RFC3339 com offset	A saída padrão é texto local truncado AAAA-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 reproduzível mais metadados reais de codec/HDR, não apenas o que play escolhe
audit	{status, message, title}	Detecta recursos bloqueados/em revisão
apps, spell_name, tags, reference_events, thumbnail_link, icon_link, web_content_link, phase, starred, trashed, writable, folder_type, revision, user_id	Campos restantes da API	Qualquer coisa que a forma reduzida descarta, incluindo campos adicionados por versões futuras da API

Semântica — leia antes de usar:

• Literal. O corpo não é recodificado: a ordem dos campos é a da API, e & em links assinados permanece um & literal (nunca \u0026). Seguro para alimentar diretamente no jq.
• Sempre estruturado. --raw implica saída JSON mesmo sem -F; -F yaml converte o mesmo corpo. Não há tabela legível por humanos neste modo.
• ls --raw é uma requisição por página, não por arquivo. Mesmas flags -p / -l / -t / --type e os mesmos filtros do lado do servidor (não excluídos, PHASE_TYPE_COMPLETE) que ls simples. A paginação é inalterada: leia next_page_token do corpo bruto e passe de volta com -t. Aumente -l (ex.: -l 500) para cobrir uma pasta grande em uma chamada em vez de fazer um loop com get.
• --type combina com --raw. É um filtro de kind do lado do servidor (drive#file / drive#folder), então o corpo passado já contém apenas o tipo solicitado e uma página ainda comporta até -l itens. Filtragem do lado do cliente com jq em .files[] | select(.kind == …) não é mais necessária.
• get --raw sempre solicita usage=ALL — a resposta mais completa — então --url-type é ignorado e não é mais necessário: medias[].link.url e web_content_link já estão no corpo. Ele também pula a verificação de atividade da URL de download, então permanece uma única requisição de leitura e nunca adiciona as chaves derivadas download_url / play_url / play_resolution.
• Os nomes diferem das formas reduzidas. Raw usa as chaves da própria API: kind é drive#file / drive#folder (não file / folder), modified_time (não modified), starred (não star).
• A presença de campo não é garantida. params está ausente ou parcial para pastas e arquivos que não são de mídia; medias costuma ser [] até que o servidor termine a transcodificação. Proteja com select(.params.duration != null) ou padrões // "0".
• Não filtre a saída bruta por file_category, e não confie em mime_type. A API frequentemente omite file_category mesmo para vídeos (a forma reduzida ls -F json o deriva), e mime_type retorna como "" em uma boa parte dos arquivos de mídia, portanto tanto select(.file_category == "video") quanto select(.mime_type | startswith("video")) descartam silenciosamente vídeos reais. O teste confiável de vídeo na saída bruta é a presença de params.duration.

Receitas:

# Vídeos com mais de uma hora (UMA chamada de API — nunca faça um loop `get` sobre uma pasta)
pikpak ls --raw | jq -r '.files[] | select((.params.duration // "0" | tonumber) > 3600)
  | "\(.name)\t\(.params.duration)s"'

# Arquivos 4K, l

…

[truncado para tradução]