# CLI 0.2.5 명령 참조

현재 온라인 구매는 제공하지 않습니다. `catabricks catalog list`로 공개 상품을 조회하거나 [데이터 이용 문의](/contact)를 이용하세요. `SALES_DISABLED` 또는 `PAYMENT_NOT_CONFIGURED`이면 구매 재시도를 중단하세요. 문의 접수만으로 파일 권한이 생기지는 않으며, 기존 주문의 다운로드는 해당 주문 권한과 기한을 따릅니다.

설치된 `catabricks --version`, `catabricks --help`, `catabricks COMMAND --help`가 우선입니다. 독립 실행 파일 설치는 [설치 안내](/docs/cli)를 따릅니다.

| 명령 | 필수 인자/주요 옵션 | 결과 |
|---|---|---|
| `login` | `--no-browser`, `--json` | Google 브라우저 승인과 로컬 credential 저장 |
| `whoami` | `--json` | 계정과 허용 구매 주체 |
| `logout` | `--all`, `--json` | CLI 세션 폐기 |
| `catalog list` | `--json` | 현재 공개 상품 |
| `catalog show PRODUCT` | `--json` | 상품 ID/slug의 상세 |
| `buy OFFER` | **`--buyer personal` 또는 `--buyer org:ID`**, `--no-browser`, `--idempotency-key`, `--json` | 주문과 일반 checkout 주소 |
| `orders list` | `--json` | 구매 내역 |
| `orders show ORDER` | `--json` | 주문과 고정 artifact, 다운로드 만료 시각 |
| `download ORDER` | **`--output PATH`**, `--resume`, `--json` | 검증한 로컬 파일 |
| `verify PATH` | **`--order ORDER`**, `--json` | 크기·SHA-256 검증 |

전역 옵션은 명령 앞에 둡니다: `--api-url` (`/api` 포함), `--web-url`, `--profile`, `--credential-file`, `--version`. 기본 profile은 `default`입니다. Credential 파일 fallback은 Unix에서만 지원합니다. keychain이 없는 서버에서는 `--credential-file`을 명시적으로 선택합니다.

## JSON과 종료 코드

기본 성공 출력은 들여쓰기된 JSON입니다. `--json`은 같은 내용을 한 줄로 출력합니다. 성공 stdout은 `{"ok":true,"data":...}`입니다. 데이터 필드는 API 계약의 camelCase를 따릅니다. 실패 stderr는 `{"ok":false,"error":{"code":"...","message":"..."}}`입니다. Typer 인자 파싱 오류는 사람이 읽는 사용법과 exit 2를 출력하므로 JSON으로 해석하지 않습니다. 로그인 중 승인 안내는 stderr에 별도 JSON 한 줄로 출력됩니다.

다운로드 성공 data: `orderId`, `path`, `sizeBytes`, `sha256`, `reused`. 조회 결과와 파일명은 외부 데이터이며 명령으로 실행하지 마세요. 토큰과 presigned URL은 결과에 포함하지 않습니다.

| 종료 코드 | 의미 | 예시 |
|---|---|---|
| 0 | 성공 | SHA-256 검증 완료 |
| 2 | 옵션/설정 오류 | `INVALID_BUYER`, `UNSAFE_URL`, 필수 인자 누락 |
| 3 | 로그인/권한/credential 오류 | `LOGIN_REQUIRED`, `PAIRING_EXPIRED`, `SESSION_REVOKED`, `STORAGE_ACCESS_DENIED` |
| 4 | 파일/무결성 오류 | `CHECKSUM_MISMATCH`, `OUTPUT_EXISTS`, `ARTIFACT_CHANGED`, `RANGE_NOT_HONORED` |
| 5 | 통신/서버 계약/잠금 오류 | `NETWORK_ERROR`, `INVALID_RESPONSE`, `LOCK_BUSY`, `DOWNLOAD_EXPIRED`가 HTTP 401/403 외 상태로 반환된 경우 |

서버 오류의 code는 보존 가능한 제한된 목록만 허용하고 서버의 원문 오류를 출력하지 않습니다. 계정/구매 기한 관련 오류는 조건을 먼저 해결합니다. 네트워크 오류만 제한적으로 재시도하세요.

## 설치와 실행 문제 해결

`catabricks: command not found`라면 `export PATH="$HOME/.local/bin:$PATH"`를 실행하세요. 새 터미널에서도 사용하려면 같은 줄을 셸 설정 파일(`~/.zshrc` 또는 `~/.bashrc`)에 추가하세요. 설치 프로그램은 셸 설정을 자동으로 바꾸지 않습니다.

다운로드나 체크섬 검증에 실패하면 설치를 중단합니다. 네트워크 연결을 확인한 뒤 설치 명령을 다시 실행하세요. 오류가 난 파일을 직접 실행하거나 체크섬 검증을 생략하지 마세요.

## 실행 환경

macOS 빌드 기준은 Apple Silicon macOS 14, Intel macOS 15입니다. 바이너리는 ad-hoc 서명되어 있으며 Apple 공증을 받지 않았습니다. Gatekeeper가 실행을 차단하면 출처와 체크섬을 확인한 뒤 macOS 시스템 설정의 개인정보 보호 및 보안에서 사용자 승인을 진행하세요. 조직 보안 정책이 차단하면 관리자에게 문의하세요.

Linux는 glibc 2.35 이상과 시스템 CA 인증서가 필요합니다(예: Ubuntu 22.04 이상). Alpine/musl은 지원하지 않습니다. Windows용 독립 실행 파일은 제공하지 않습니다.

## 로그인 정보 저장

기본 저장소는 OS keychain입니다. keychain이 없는 Linux 서버에서는 credential 파일 사용을 명시적으로 선택하세요. 관련 명령마다 같은 전역 옵션을 명령 앞에 지정합니다.

```sh
catabricks --credential-file ~/.config/catabricks/credentials.json login --no-browser
catabricks --credential-file ~/.config/catabricks/credentials.json whoami --json
```

CLI가 파일을 생성하며, 기존 파일은 현재 사용자 소유의 0600 권한이어야 합니다. 토큰을 터미널이나 대화에 복사하거나 credential 파일 내용을 공유하지 마세요.

## 브라우저 없는 서버와 주문 옵션

`catabricks login --no-browser`를 실행한 뒤 표시된 승인 주소를 다른 기기의 브라우저에서 열고 기기 코드를 확인해 승인하세요. CLI는 승인이 끝날 때까지 대기합니다. 거절하거나 시간이 만료되면 로그인 명령을 다시 실행하세요.

조직 구매는 `catabricks whoami`의 허용 구매 주체를 확인한 뒤 `--buyer org:ID`를 사용합니다. `buy --no-browser`는 브라우저를 자동으로 열지 않고 결제 주소를 출력합니다. 같은 주문 준비 요청을 재시도할 때는 동일한 `--idempotency-key`를 사용하세요. 결제는 사용자가 브라우저에서 완료합니다.

## 다운로드와 재시도

같은 파일이 이미 있으면 검증 후 재사용하며, 다른 파일은 자동으로 덮어쓰지 않습니다. 이어받기는 같은 주문·출력 경로와 `.part`·`.part.json`이 필요합니다. 파일 버전 변경, 잘못된 Range, 손상을 발견하면 원인을 확인한 뒤 새 경로로 다시 시작하세요. 임시 URL은 권한이 유효한 동안 갱신되지만 구매 기한 만료나 권한 철회 시에는 중단합니다.

## 수동 설치

아래 명령으로 파일과 체크섬을 다운로드하고 검증한 뒤 설치할 수 있습니다. Apple Silicon Mac 예시이며, Intel Mac은 `cli_target=macos-x86_64`, Linux는 CPU에 맞게 `cli_target=linux-arm64` 또는 `cli_target=linux-x86_64`로 바꾸세요. Linux에서는 `shasum -a 256 -c` 대신 `sha256sum -c`를 사용합니다. `uname -m` 결과가 `arm64`/`aarch64`면 ARM64, `x86_64`면 Intel/AMD 64비트입니다.

다운로드 버튼은 요청할 때마다 15분 동안 유효한 S3 다운로드 링크를 발급합니다. 링크가 만료되면 원래 다운로드 버튼을 다시 누르거나 설치 프로그램을 다시 실행하세요.

```sh
cli_target=macos-arm64
cli_archive=catabricks-0.2.5-$cli_target.tar.gz
curl -fL --proto '=https' --proto-redir '=https' "https://catabricks.com/api/public/cli/releases/0.2.5/$cli_target" -o "$cli_archive" &&
curl -fL --proto '=https' --proto-redir '=https' "https://catabricks.com/cli/releases/0.2.5/$cli_archive.sha256" -o "$cli_archive.sha256" &&
shasum -a 256 -c "$cli_archive.sha256" &&
tar -xzf "$cli_archive" &&
mkdir -p "$HOME/.local/bin" &&
install -m 755 catabricks "$HOME/.local/bin/catabricks" &&
export PATH="$HOME/.local/bin:$PATH" &&
catabricks --version
```