PikPak CLI 조작 스킬
pikpak 명령줄 도구를 통해 PikPak 클라우드 저장소를 조작합니다.
pikpak 설치
운영체제에 따라 설치 방법을 선택하세요:
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
설치 후 pikpak version을 실행하여 확인합니다.
초대 코드 사용 시 — 설치 프로그램이 이 컴퓨터에서 추후 실행될 pikpak auth register를 위해 코드를 저장합니다. 초대 API에 접촉하지 않습니다:
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>
설치 프로그램은 코드를 별도의 일반 텍스트 affiliate 파일에 저장합니다. Python이나 JSON 파서가 필요하지 않으며, settings.json은 절대 읽거나 수정되지 않습니다. 쓰기 실패 시 경고는 발생하지만 설치가 실패하지 않으며 이전 코드를 덮어쓰지 않습니다. 이 경우 pikpak auth register --affiliate <code>를 사용하여 코드를 전달하세요.
pikpak skill install은 이 문서를 컴퓨터에 있는 모든 AI 코딩 에이전트(Claude Code, Codex, Gemini CLI, opencode, Cursor, goose, iFlow, Qwen Code 등)의 스킬 디렉토리에 씁니다. 이 문서가 설치된 바이너리와 일치하지 않는 경우 pikpak update 후에 실행하세요. pikpak skill ls는 설치 위치와 최신 상태 여부를 보여줍니다.
환경 변수
| 변수 | 설명 | 기본값 |
|---|---|---|
PIKPAK_DIR | 자격 증명 디렉토리 | ~/.pikpak |
PIKPAK_CREDENTIALS | OAuth 자격 증명 파일의 전체 경로 | ~/.pikpak/.credentials.json |
PIKPAK_TOKEN | 개인 액세스 토큰; 저장된 자격 증명보다 우선함 | 설정 안 됨 |
PIKPAK_PAT_PATH | auth token으로 저장된 PAT 파일의 전체 경로 | ~/.pikpak/.pat.json |
PIKPAK_VERSION | 설치 시 지정된 버전 | 최신 |
PIKPAK_INSTALL_DIR | 설치 디렉토리 | ~/.local/bin (macOS/Linux), %USERPROFILE%\.pikpak (Windows) |
PIKPAK_NO_UPDATE_NOTIFIER | 1로 설정하면 자동 업데이트 확인 및 알림 비활성화; 명시적 version --check와 update는 여전히 작동 | 설정 안 됨 |
PIKPAK_NO_LOG | 비어 있지 않은 값(예: 1)으로 설정하면 config log를 무시하고 진단 로그 기록 안 함 | 설정 안 됨 |
PIKPAK_NO_SKILL_SYNC | 비어 있지 않은 값으로 설정하면 pikpak update가 설치된 에이전트 스킬을 새로 고치지 않음 | 설정 안 됨 |
PIKPAK_AFFILIATE | 설치 시 install.sh / install.ps1이 읽는 초대 코드 (CLI 자체는 이를 읽지 않음) | 설정 안 됨 |
자격 증명 우선순위: PIKPAK_TOKEN → pikpak auth token으로 저장된 PAT → pikpak auth login의 OAuth 자격 증명.
장치 식별: CLI는 설치당 하나의 안정적인 장치 ID를 ~/.pikpak/.device.json에 유지합니다(X-Device-Id). 모든 로그인 방법에서 재사용되며 토큰 순환 및 auth logout 후에도 유지됩니다. 삭제하면 해당 머신이 PikPak의 위험 관리에 완전히 새로운 장치로 보입니다.
인증
대부분의 명령은 먼저 로그인이 필요합니다. 자격 증명은 ~/.pikpak/.credentials.json에 저장됩니다.
pikpak auth login # 로그인 방법 자동 감지 (가능하면 브라우저, 그렇지 않으면 장치 흐름)
pikpak auth login -m browser # 브라우저 OAuth 로그인 (브라우저 열림, 30초 응답 없음 -> 장치 흐름으로 대체)
pikpak auth login -m browser --no-launch-browser # 브라우저 OAuth 로그인 (URL 출력, 자동 열기 안 함)
pikpak auth login -m device # 장치 흐름 (QR 코드 + 확인 URL + 자동 폴링)
pikpak auth login -m device -F json # 장치 흐름: 인증 정보를 JSON으로 출력하고 종료 (폴링 없음, AI용)
pikpak auth login --continue <device_code> # 장치 코드 상태를 한 번 폴링하고 종료 (-F json과 함께 사용)
pikpak auth login --force # 이미 인증된 경우에도 재로그인
pikpak auth login -l "my-session" # 사용자 지정 세션 레이블 설정
pikpak auth login --scope files:manage,cloud_download # OAuth 범위 미리 선택 (쉼표로 구분)
pikpak auth register # 새 계정 등록 (로그인과 동일한 브라우저/장치 흐름)
pikpak auth register --affiliate <code> # 제휴/초대 코드로 등록
pikpak auth register --affiliate= # 이 등록에 대해 설치 프로그램이 저장한 코드 건너뛰기
pikpak auth register -m device # 등록에 장치 흐름 강제
pikpak auth token <token> # 비대화형 사용을 위한 개인 액세스 토큰 저장
pikpak auth logout # 로컬 세션 지우기; 오프라인 및 손상/만료된 자격 증명에서 작동 (환경 변수에서 PIKPAK_TOKEN을 제거할 수 없음)
pikpak auth status # 로그인 상태 + 계정 패널: 신원, VIP, 저장소 할당량 (스크립트용으로 -F json 추가)
지원되는 --scope 식별자: files:read, files:write, files:manage, files:purge, cloud_download, share, invite, account. --scope를 생략하면 범위를 보내지 않으며 인증 서버가 기본값을 적용합니다.
AI 에이전트 로그인 가이드: 비밀번호 로그인은 더 이상 지원되지 않습니다. 비대화형/AI 환경에서는 장치 흐름을 사용하세요:
pikpak auth login -m device -F json을 실행하여device_code,verification_uri,user_code,expires_in,interval을 가져옵니다.- 사용자에게 확인 URL과 코드(또는 QR 코드)를 보여줍니다.
status가success가 될 때까지pikpak auth login --continue <device_code> -F json으로 폴링합니다.환경이 브라우저를 지원하는 경우(macOS/Linux GUI),
pikpak auth login(자동 감지) 또는pikpak auth login -m browser가 플래그 없이 작동합니다. 로그인은 기존 자격 증명을 먼저 확인합니다. 새 세션을 만들려면--force를 사용하세요.완전 비대화형 대안:
pikpak auth token <PAT>을 사용하거나PIKPAK_TOKEN=<PAT>을 내보냅니다.등록 주의사항:
pikpak auth register -F json은signup_uri,handoff_code,qr_png_path,expires_in(그리고 코드가 관련된 경우affiliate— 플래그 또는 기록)을 출력하고 종료됩니다.device_code를 반환하지 않으므로--continue로 폴링할 수 없습니다. AI 기반 등록의 경우-F없이pikpak auth register를 실행하거나(대화형으로 폴링), 사용자가 브라우저에서 등록한 후pikpak auth login을 사용하세요.
명령어 레퍼런스
파일 탐색
루트 디렉토리 ID는 빈 문자열 ""이며 / 또는 /root가 아닙니다.
pikpak ls # 루트 디렉토리 목록
pikpak ls <folderID> # 지정된 폴더 목록 (위치 인자)
pikpak ls -p <folderID> # 동일, 플래그 사용 (둘 다 제공되면 위치 인자 우선)
pikpak ls --type file # 파일만 표시 (서버 측 종류 필터, --raw와도 작동)
pikpak ls --type folder # 폴더만 표시 (서버 측 종류 필터, --raw와도 작동)
pikpak ls -l 50 # 페이지당 항목 수 (--limit, 기본값 100; 서버는 10 미만 값을 10으로 올림)
pikpak ls -t <token> # 페이지 매김 (--token, 이전 ls 출력에서)
pikpak ls -F json # JSON 출력 (AI 선호: id, parent_id, name, kind, size, mime_type, file_category, modified, hash; mime_type/file_category는 폴더와 서비스가 분류하지 않은 파일에 대해 생략됨)
pikpak ls --raw # 전체 목록의 수정되지 않은 API JSON: params.duration/width/height, params.url, audit, thumbnail_link, spell_name, apps 추가; size는 바이트 단위
휴지통에 있지 않고 완전히 처리된 파일만 나열됩니다. 하나의 ls는 한 페이지입니다: 출력에서 next_page_token을 읽고 -t로 다시 전달하여 계속합니다. -l은 페이지 크기 요청이지 하드 캡이 아닙니다. 서비스는 더 작은 값에 대해 10개 항목을 반환하며, 폴더가 끝날 때 페이지가 -l보다 짧게 반환될 수도 있습니다.
파일 검색 (사용 불가)
search 명령은 서버 측 검색 API를 사용할 수 없기 때문에 이 릴리스에서 비활성화되었습니다. pikpak search를 제안하거나 실행하지 마세요. 대신 pikpak ls(선택적으로 -F json)로 폴더를 탐색하여 파일을 찾으세요.
파일 상세 정보
pikpak get <fileID> # 기본 정보
pikpak get <fileID> --url-type download # 다운로드 URL 포함
pikpak get <fileID> --url-type play # 재생 URL 포함
pikpak get <fileID> --url-type all # 모든 URL 포함
pikpak get <fileID> --raw # 수정되지 않은 API JSON (usage=ALL; url_type 무시)
get -F json 필드: id, name, type (file/folder), size, mime, hash, created, modified, phase, 그리고 --url-type이 요청할 때 download_url, play_url, play_resolution이 추가됩니다. ls와 명명 방식이 다릅니다: 여기서는 type/mime이고 거기서는 kind/mime_type입니다. URL은 파일에 대해서만 반환됩니다. 폴더에 --url-type을 사용하면 메타데이터만 반환됩니다.
--raw는 이 축소된 형태를 완전히 우회합니다. 아래 원시 API 출력을 참조하세요.
원시 API 출력 (--raw)
pikpak ls --raw와 pikpak get <fileID> --raw는 PikPak 드라이브 API의 응답 본문을 그대로 인쇄합니다(들여쓰기만 다시 함). 필요한 필드가 위의 축소된 ls / get 형태에 없는 경우 사용하세요.
pikpak ls --raw # 전체 목록, API가 반환하는 모든 필드
pikpak ls --raw -p <folderID> -l 500 # 일반 ls와 동일한 필터/페이지 매김 플래그
pikpak get <fileID> --raw # 하나의 파일, usage=ALL
pikpak ls --raw -F yaml # 동일한 본문을 YAML로 변환
--raw가 추가하는 것 (ls -F json의 9개 필드 외에, 파일당):
| 원시 필드 | 의미 | 중요한 이유 |
|---|---|---|
params.duration | 재생 길이(초), 문자열 ("1420") | 비디오 길이의 유일한 출처 — ls와 get 기본 출력에 모두 없음 |
params.width / params.height | 픽셀 크기, 문자열 ("1920" / "1080") | 해상도 필터링; get --url-type play는 1080p와 같은 레이블만 제공 |
params.url | 파일 출처: 토렌트의 경우 magnet:?xt=urn:btih:…, 링크 다운로드의 경우 http(s) URL | 오프라인 다운로드 소스의 유일한 기록 |
params.task_id | 파일을 생성한 오프라인 작업의 ID | 파일을 pikpak task get <taskID>에 연결 |
params.db_modify_time, params.platform, params.platform_icon, params.original_share_id | 서비스 측 메타데이터, 모든 항목에 있음 | 출처 |
size | 원시 바이트 문자열 ("392927574") | 기본 출력은 형식화(375 MB)하여 숫자로 비교 불가 |
created_time / modified_time / user_modified_time | 오프셋이 있는 RFC3339 | 기본 출력은 잘린 로컬 YYYY-MM-DD HH:MM 텍스트 |
medias[] | 전체 배열: 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,…} | play가 선택하는 하나뿐 아니라 모든 재생 가능 변형과 실제 코덱/HDR 메타데이터 |
audit | {status, message, title} | 차단/검토 중인 리소스 감지 |
apps, spell_name, tags, reference_events, thumbnail_link, icon_link, web_content_link, phase, starred, trashed, writable, folder_type, revision, user_id | 나머지 API 필드 | 축소된 형태가 생략하는 모든 것, 향후 API 버전에서 추가된 필드 포함 |
의미 — 사용 전에 읽으세요:
- 그대로. 본문이 재인코딩되지 않습니다: 필드 순서는 API의 순서이며, 서명된 링크의
&는 리터럴&로 유지됩니다(\u0026가 아님).jq에 바로 전달 가능. - 항상 구조화됨.
--raw는-F없이도 JSON 출력을 의미합니다.-F yaml은 동일한 본문을 변환합니다. 이 모드에서는 사람이 읽을 수 있는 테이블이 없습니다. ls --raw는 페이지당 하나의 요청이지 파일당이 아닙니다. 일반ls와 동일한-p/-l/-t/--type플래그 및 동일한 서버 측 필터(휴지통 없음,PHASE_TYPE_COMPLETE)가 적용됩니다. 페이지 매김은 동일합니다: 원시 본문에서next_page_token을 읽고-t로 다시 전달하세요. 큰 폴더를 하나의 호출로 처리하려면-l을 높게 설정하세요(예:-l 500).get을 반복하는 대신 사용합니다.--type은--raw와 결합됩니다. 서버 측kind필터(drive#file/drive#folder)이므로, 통과 본문에는 이미 요청된 종류만 포함되며 페이지는 여전히 최대-l개의 항목을 유지합니다..files[] | select(.kind == …)에 대한 클라이언트 측jq필터링이 더 이상 필요하지 않습니다.get --raw는 항상usage=ALL을 요청합니다 — 가장 완전한 응답 — 따라서--url-type은 무시되며 더 이상 필요하지 않습니다:medias[].link.url및web_content_link가 이미 본문에 있습니다. 또한 다운로드 URL 활성 프로브를 건너뛰므로 단일 읽기 요청으로 유지되며 파생된download_url/play_url/play_resolution키를 추가하지 않습니다.- 이름이 축소된 형태와 다릅니다. 원시는 API의 자체 키를 사용합니다:
kind는drive#file/drive#folder입니다 (file/folder가 아님),modified_time(modified가 아님),starred(star가 아님). - 필드 존재는 보장되지 않습니다.
params는 폴더 및 비미디어 파일에 대해 없거나 불완전합니다.medias는 서버가 트랜스코딩을 완료할 때까지 종종[]입니다.select(.params.duration != null)또는// "0"기본값으로 보호하세요. - 원시 출력을
file_category로 필터링하지 말고mime_type에 의존하지 마세요. API는 비디오에서도file_category를 자주 생략하며(축소된ls -F json형태가 이를 파생함),mime_type은 상당수의 미디어 파일에서""로 반환되므로select(.file_category == "video")와select(.mime_type | startswith("video"))모두 실제 비디오를 조용히 놓칩니다. 원시 출력에서 신뢰할 수 있는 비디오 테스트는params.duration의 존재 여부입니다.
레시피:
# 1시간보다 긴 비디오 (API 호출 한 번 — 폴더에 대해 `get`을 절대 반복하지 마세요)
pikpak ls --raw | jq -r '.files[] | select((.params.duration // "0" | tonumber) > 3600)
| "\(.name)\t\(.params.duration)s"'
# 4K 파일, 목록
…
[번역을 위해 잘림]