> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AIHubMix CLI(명령줄 도구)

> AIHubMix CLI는 AIHubMix 공식 명령줄 도구로, 단일 바이너리·제로 의존성을 갖추고 있어 터미널에서 바로 계정 잔액 조회, API Key 관리, 사용 가능한 모델 확인이 가능하며 스크립트 및 AI Agent에 친화적입니다.

**AIHubMix CLI**는 AIHubMix 공식 명령줄 도구입니다(실행 파일 `aihubmix`). 설치하면 웹 콘솔을 열지 않고도 터미널에서 계정 잔액 조회, API Key 관리, 사용 가능한 모델 확인을 할 수 있습니다. 단일 바이너리 파일이라 **Python, Node, Go를 설치할 필요 없이** 명령 한 줄로 설치가 완료됩니다. 모든 명령이 JSON 출력을 지원하여 스크립트, CI, AI Agent(예: Claude Code)에 바로 연동할 수 있습니다.

**무엇을 할 수 있나요:**

* **잔액 조회**: 계정 잔액과 사용한 금액을 실시간으로 조회
* **Key 관리**: API Key 생성, 조회, 검색, 수정, 삭제
* **모델 확인**: 현재 토큰으로 사용 가능한 모델 목록 조회
* **스크립트화 가능**: JSON 출력 + 안정적인 종료 코드로 자동화와 AI Agent에 자연스럽게 적합

<Info>
  **두 가지 자격 증명을 혼동하지 마세요**: CLI는 「시스템 액세스 토큰」(Manage Key, 형식 `fd***`)으로 로그인하며, 콘솔 [console.aihubmix.com/setting](https://console.aihubmix.com/setting)에서 「시스템 액세스 토큰 생성」을 클릭하여 발급받습니다. 이는 **계정 관리**에 사용되며, 모델 호출 시 사용하는 API Key(`sk-***`)와는 다릅니다.
</Info>

<Tip>
  구버전 Python 스크립트(`aihubmix_cli.py`)를 찾고 계신가요? [인터페이스를 통한 계정 정보 조회](/ko/api/Cli)를 참고하세요. 이 페이지에서 소개하는 것은 그 차세대 대체품으로, 더 간단하고 더 빠릅니다.
</Tip>

## 설치

### 원클릭 설치(권장)

사용 중인 시스템에 맞는 명령을 복사하여 터미널에 붙여넣고 실행하면 바이너리를 다운로드하고 자동으로 `PATH`에 추가합니다:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl -fsSL https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.sh | sh
  ```

  ```powershell Windows PowerShell theme={null}
  irm https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.ps1 | iex
  ```
</CodeGroup>

설치가 끝나면 **터미널을 새로 열고** `aihubmix login`을 실행하여 사용을 시작하세요.

<Info>
  [Releases](https://github.com/AIhubmix/platfrom-cli/releases)에서 해당 플랫폼의 바이너리를 직접 다운로드할 수도 있습니다(Windows는 `aihubmix_windows_amd64.exe`). `PATH` 디렉터리에 넣으면 되며, Unix 계열 시스템에서는 `chmod +x`가 필요합니다.
</Info>

필요하면 환경 변수로 설치 동작을 조정할 수 있습니다:

| 변수                 | 설명                     | 기본값                                                                              |
| ------------------ | ---------------------- | -------------------------------------------------------------------------------- |
| `AIHUBMIX_VERSION` | 지정한 버전 설치(예: `v0.2.0`) | `latest`                                                                         |
| `AIHUBMIX_BIN_DIR` | 사용자 지정 설치 디렉터리         | Unix: `/usr/local/bin` 또는 `~/.local/bin`; Windows: `%LOCALAPPDATA%\aihubmix\bin` |

## 빠른 시작

로그인하면 모든 명령을 사용할 수 있습니다:

```bash theme={null}
# 1. 로그인: 브라우저에서 토큰 생성 페이지를 자동으로 열고 Manage Key를 붙여넣기(입력 시 표시 안 됨)
aihubmix login

# 2. 현재 신원 및 잔액 확인
aihubmix whoami

# 3. 전체 계정 정보 확인
aihubmix me

# 4. API Key 목록 조회
aihubmix keys list
```

## 명령 참조

| 명령                                 | 기능                   |
| ---------------------------------- | -------------------- |
| `aihubmix login`                   | 로그인(Manage Key 붙여넣기) |
| `aihubmix logout`                  | 로그아웃, 로컬 자격 증명 삭제    |
| `aihubmix whoami`                  | 현재 로그인 신원 및 잔액 확인    |
| `aihubmix me`                      | 전체 계정 정보 및 잔액 확인     |
| `aihubmix models list`             | 현재 사용 가능한 모델 확인      |
| `aihubmix keys list [--num N]`     | API Key 목록 조회        |
| `aihubmix keys search <키워드>`       | 키워드로 Key 검색          |
| `aihubmix keys get <id>`           | 지정한 Key 세부 정보 확인     |
| `aihubmix keys create [파라미터]`      | 새 Key 생성             |
| `aihubmix keys update <id> [파라미터]` | Key 수정               |
| `aihubmix keys delete <id>`        | Key 삭제               |

<Tip>
  아무 명령에나 `--help`를 붙이면 전체 파라미터를 확인할 수 있습니다. 예: `aihubmix keys create --help`.
</Tip>

## 자주 쓰는 작업

### API Key 관리

```bash theme={null}
# $10 한도, 지정한 모델만 사용 가능한 Key 생성
aihubmix keys create -n prod-key -q 10 -m "gpt-4o,claude-3.5-sonnet"

# 한도 없음, 만료 없음인 Key 생성
aihubmix keys create -n ci-key -u

# Key 이름 변경(나머지 설정은 그대로 유지)
aihubmix keys update 123 -n new-name

# 특정 Key 비활성화
aihubmix keys update 123 --status 0

# Key 삭제
aihubmix keys delete 123
```

여기서 `-q 10`은 해당 Key의 한도가 \$10임을 의미하고, `-u`는 한도 없음을 의미합니다. 삭제는 기본적으로 확인을 요구하며, CI 환경에서는 `--yes`를 붙여 건너뛸 수 있습니다.

### 스크립트 / AI Agent에서 사용

CLI는 자동화에 매우 친화적이어서 CI, 스크립트 또는 AI Agent(예: Claude Code)에서 바로 구동할 수 있습니다:

* **로그인 없이 사용**: 환경 변수 `AIHUBMIX_TOKEN` 또는 `--token`으로 Manage Key를 전달하여 인터랙티브 로그인을 건너뜁니다(우선순위: `--token` > `AIHUBMIX_TOKEN` > 설정 파일).
* **JSON 출력**: 아무 명령에나 `--json`(`-j`)을 붙이면 정상 결과는 stdout으로, 오류는 stderr로 출력되어 `jq` 파싱에 편리합니다.
* **안정적인 종료 코드**: 스크립트는 이를 기반으로 성공 여부를 판단할 수 있습니다.

```bash theme={null}
# 환경 변수로 구동하여 모든 Key 이름 추출
AIHUBMIX_TOKEN=fd*** aihubmix keys list --json | jq '.data[].name'

# 잔액 조회
AIHUBMIX_TOKEN=fd*** aihubmix whoami --json | jq -r '.balance'
```

종료 코드의 의미:

| 종료 코드 | 의미                          |
| ----- | --------------------------- |
| `0`   | 성공                          |
| `1`   | 일반 오류(파라미터 오류, 비즈니스 실패 등)   |
| `2`   | 인증 실패(미로그인 / Token 유효하지 않음) |
| `3`   | 네트워크 / 연결 오류                |

## 전역 파라미터

다음 파라미터는 모든 명령에 적용됩니다:

| 파라미터               | 단축키  | 설명                                        |
| ------------------ | ---- | ----------------------------------------- |
| `--token <token>`  | `-t` | Manage Key를 직접 전달(CI / 스크립트 환경)           |
| `--json`           | `-j` | JSON 형식으로 출력                              |
| `--base-url <url>` | `-b` | API 주소 사용자 지정(기본값 `https://aihubmix.com`) |
| `--no-color`       |      | 컬러 출력 비활성화                                |
| `--config <path>`  |      | 설정 파일 경로 지정                               |
| `--version`        |      | 버전 확인                                     |

## 설정 파일

로그인 정보는 `~/.aihubmix/config.json`(Windows는 `%USERPROFILE%\.aihubmix\config.json`)에 저장되며, 권한은 **현재 사용자만 읽고 쓸 수 있도록** 제한됩니다. 로그인 시 Manage Key는 화면에 표시되지 않고 로그에도 기록되지 않습니다.

<Warning>
  Manage Key를 코드 저장소에 커밋하거나 타인과 공유하지 마세요. 유출되면 콘솔에서 재생성하세요. 기존 토큰은 즉시 무효화됩니다.
</Warning>

## 자주 묻는 질문

**Python / Node / Go를 설치해야 하나요?**

아니요. CLI는 단일 바이너리 파일이라 다운로드하면 바로 사용할 수 있습니다.

**Manage Key와 API Key는 어떤 차이가 있나요?**

Manage Key(`fd***`)는 계정 관리(잔액 조회, Key 관리)에 사용되며 CLI가 사용합니다. API Key(`sk-***`)는 모델 호출에 사용됩니다. 두 가지는 콘솔의 서로 다른 위치에서 생성되며 혼용할 수 없습니다.

**Windows를 지원하나요?**

지원합니다. Windows, macOS, Linux 모두 네이티브 바이너리를 제공합니다.

**CI / 스크립트에서 인터랙션 없이 사용하려면?**

환경 변수 `AIHUBMIX_TOKEN`으로 Manage Key를 전달하고 `--json`과 종료 코드를 함께 활용하면 됩니다. `aihubmix login`을 실행할 필요가 없습니다.

**Manage Key를 잊어버렸거나 유출되었다면?**

[console.aihubmix.com/setting](https://console.aihubmix.com/setting)에서 재생성하세요. 기존 토큰은 즉시 무효화됩니다.

***

*관련 문서: [플랫폼 API · CliEndpoints](/ko/api/CliEndpoints/get-self) · [구버전 Python 스크립트](/ko/api/Cli) · [AIHubMix 콘솔](https://console.aihubmix.com)*

***

최종 업데이트: 2026-06-22