# gujoctl

> 터미널에서 로그인하고 산 제품을 설치하는 구매자 CLI.

gujoctl 은 macOS·Linux 용 실행 파일 하나입니다. 브라우저 승인으로 로그인하고, 내 라이브러리를 보고, 산 제품을 내려받아 확인한 뒤 설치합니다.

## 설치

```bash
curl -fsSL "https://gujo.ai/download/gujo-install.sh?channel=dev" | sh
```

설치 스크립트는 그 채널에서 내 플랫폼(`darwin-arm64`·`darwin-amd64`·`linux-amd64`·`linux-arm64`)의 최신 릴리스를 받아 sha256 을 확인하고 `~/.local/bin` 에 둡니다. 다른 폴더에 두려면 `GUJOCTL_BIN_DIR` 을 정합니다.

지금 열려 있는 채널은 `dev` 입니다. 채널을 적지 않은 주소(stable)는 아직 닫혀 있습니다.

## 로그인

```bash
gujoctl login
```

1. gujoctl 이 사용자 코드를 보여 주고 브라우저에서 account 호스트의 승인 화면을 엽니다.
2. 브라우저에서 Gujo 계정으로 로그인한 채 코드를 확인하고 승인합니다.
3. gujoctl 이 승인을 기다리다 계정 API 키를 받아 저장합니다.

브라우저를 열 수 없는 서버에서는 `gujoctl login --no-browser` 로 주소와 코드만 받고, 다른 기기의 브라우저에서 승인합니다.

받은 키는 기기 로그인 키입니다. 능력은 `products.read`·`device.entitlements`·`device.activate`·`device.install`·`device.usage`·`support.report` 여섯 가지이고 `mcp.read` 는 없습니다. 에이전트를 MCP 로 연결하려면 [시작하기](getting-started.md)대로 키를 따로 만듭니다.

키는 기기의 표준 비밀 저장소에 둡니다. macOS 는 Keychain, Linux 는 secret-service(세션 버스가 있을 때), 둘 다 없으면 권한 600 파일입니다.

## 명령

| 명령 | 하는 일 |
|---|---|
| `gujoctl login [--no-browser]` | 기기 로그인. 코드를 보여 주고 브라우저 승인을 기다립니다 |
| `gujoctl logout` | 서버에서 이 기기의 키를 폐기하고 기기에서 지웁니다 |
| `gujoctl library list` | 쓸 수 있는 상품 목록(숫자 id) |
| `gujoctl install <id> [--channel <c>] [--dir <path>]` | 설치 계획을 받아 내려받고 sha256 을 확인한 뒤 풉니다 |
| `gujoctl version` | 버전·커밋·OS/아키텍처 |
| `gujoctl help` | 사용법 |

전역 옵션:

- `--json`: stdout 에 JSON 만 씁니다. 진행 안내는 stderr 로 갑니다.
- `--api-url <url>`: API 주소를 바꿉니다. 기본값은 `https://api.gujo.ai` 이고 `GUJO_API_URL` 로도 정합니다.

## 설치하기

```bash
gujoctl library list
gujoctl install 42
```

`install` 은 서버의 설치 계획(`GET /api/products/{id}/install`)을 받아 서명 다운로드 주소에서 파일을 내려받고, sha256 이 다르면 풀지 않습니다. 채널은 `--channel stable|beta|alpha|dev` 로 고르고, 적지 않으면 stable 입니다. 설치 위치는 서버가 알려 준 대상이 정합니다.

| 대상 | 설치 위치 |
|---|---|
| `agent-skill`(에이전트 스킬, tar.gz) | `--dir` 또는 `INSTALL_DIR`. 없으면 `~/.claude` → `~/.codex` → `~/.gemini/antigravity-cli` 가운데 있는 곳의 `skills/<이름>`, 저장소 안이면 `./.agents/skills/<이름>`, 그것도 아니면 `~/.local/share/gujo/assets/<이름>` |
| `macos-app`(앱, zip) | `.app` 하나를 `/Applications`(쓸 수 없으면 `~/Applications`) 또는 `--dir` 로 옮깁니다 |

기존 설치는 새 것이 자리 잡은 뒤에 지웁니다. 아카이브 안의 절대 경로, `..`, 밖을 가리키는 심볼릭 링크는 거부합니다. 키는 API 호스트에만 보내고 다운로드 주소에는 보내지 않습니다.

## 설정과 환경 변수

| 변수 | 뜻 |
|---|---|
| `GUJO_API_URL` | API 주소(`--api-url` 과 같음) |
| `GUJOCTL_SECRET_STORE` | 비밀 저장소 고르기: `keychain`·`secret-service`·`file` |
| `GUJOCTL_CONFIG_DIR` | 설정 폴더. 기본값은 `~/.config/gujoctl` 입니다 |

설정 폴더의 `config.json` 에는 비밀이 아닌 로그인 정보만 들어갑니다. 파일 저장소를 쓰면 키는 같은 폴더의 `credentials.json` 에 들어갑니다.

## 종료 코드

| 코드 | 뜻 |
|---|---|
| 0 | 성공 |
| 1 | 오류 |
| 2 | 사용법 |
| 3 | 로그인 필요(401) |
| 4 | 권한 없음(403) |

스크립트에서는 종료 코드 3 을 받으면 `gujoctl login` 을 다시 하라고 안내하면 됩니다.