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

# CLI 설치와 로그인

> 사전 준비, 다섯 단계 설치, 브라우저 로그인, 검증, 업데이트, SSH 콜백

## CLI 설치, 로그인, 검증

CLI는 macOS, Windows, Linux를 지원하며 **Node.js 22+** 환경이 필요합니다. 에이전트가 명령을 실행하는 컴퓨터와 사용자 환경에 설치하세요. 터미널 사용자는 수동 설치 단계를 따르면 됩니다.

### 에이전트에게 EvoLink 설치 요청하기

아래 프롬프트 전체를 에이전트의 **채팅 입력란**에 붙여넣으세요. 웹사이트의 프롬프트와 같은 내용입니다. 브라우저 로그인과 권한 승인은 직접 완료하세요.

```text theme={null}
여기서 이미지, 동영상, 오디오를 바로 생성할 수 있도록 EvoLink를 설정해 주세요.
1. CLI 설치: `npm install -g @evolinkai/cli`를 실행하세요.
2. 로그인: `evolink auth login`을 실행하세요.
3. 함께 제공되는 스킬 설치: `evolink skills install`을 실행하세요.
4. 연결을 확인하고 성공하면 시작할 수 있다고 알려 주세요.
```

에이전트가 터미널 명령을 실행할 수 없다면 아래의 수동 설치 단계를 따르세요. `bash` 블록은 **터미널**에서 한 단계씩 실행하세요. 두 가지 설치 방법을 모두 수행할 필요는 없습니다.

### 수동 설치: 다섯 단계

**1. Node.js와 실행 환경 확인**

에이전트를 실행하는 컴퓨터에서, 에이전트를 실행하는 사용자 계정으로 터미널을 여세요. macOS에서는 Terminal, Windows에서는 PowerShell 또는 명령 프롬프트를 사용하거나 Cursor의 통합 터미널을 사용하세요.

```bash theme={null}
node --version
npm --version
```

**성공 표시**: 두 명령 모두 버전을 표시하며 Node.js는 22 이상입니다. 설치되어 있지 않거나 버전이 오래되었다면 [Node.js](https://nodejs.org/en/download)에서 알맞은 버전을 설치하고, 터미널을 다시 연 뒤 다시 확인하세요. WSL, SSH 호스트, 컨테이너, 데스크톱은 서로 다른 환경입니다. 에이전트가 명령을 실행하는 환경에 설치하세요.

**2. CLI 설치 및 확인**

```bash theme={null}
npm install -g @evolinkai/cli
evolink --version
```

**성공 표시**: 설치가 오류 없이 끝나고 `evolink --version`이 CLI 버전을 표시합니다. `-g`는 현재 Node/npm 전역 디렉토리에 명령을 설치합니다. MCP나 플러그인 저장소를 복제할 필요는 없습니다. 계속하기 전에 [설치 문제](https://evolink.ai/docs/ko/cli/billing.md#cli-install)를 먼저 해결하세요.

**3. EvoLink에 로그인**

```bash theme={null}
evolink auth login
```

1. 명령을 실행 중인 상태로 두세요. 브라우저가 열리거나 이번 로그인 시도의 로그인 링크가 출력됩니다.
2. EvoLink에 로그인하고 계정, 클라이언트, 요청된 권한을 확인한 뒤 승인하세요.
3. 원래 터미널로 돌아와 완료될 때까지 기다린 뒤 다음을 실행하세요:

```bash theme={null}
evolink auth status --json
```

**성공 표시**: `authenticated: true`. CLI는 운영 체제의 보안 자격 증명 저장소를 사용하므로 API Key를 만들거나 붙여넣을 필요가 없습니다. 브라우저 콜백만으로는 터미널 로그인이 완료되지 않습니다. 잔액 조회를 통한 연결 확인은 마지막 단계에서 합니다. 브라우저, 시간 초과, Linux 저장소 오류는 [로그인 문제 해결](https://evolink.ai/docs/ko/cli/billing.md#login)을 참고하세요.

**4. 스킬 설치 및 에이전트 인식 확인**

```bash theme={null}
evolink skills install
evolink skills status --json
```

`--agent`를 지정하지 않으면 지원되는 모든 스킬 디렉토리에 설치합니다. 해당 에이전트 자체를 설치하는 것은 아닙니다. 호스트 하나만 선택하려면 아래 표에 나온 agent 값을 사용하세요.

**성공 표시**: `current: true`. 에이전트 채팅에 다음을 보내세요:

```text theme={null}
이 세션에서 evolink-cli 스킬을 인식하고 읽을 수 있는지 확인해 주세요. 먼저 연결을 검증하고, 미디어는 생성하지 마세요.
```

이 스킬은 모델 탐색, 매개변수, 예상 비용과 승인, 참조 파일, 작업, 원본 다운로드를 안내합니다. 네이티브 MCP를 등록하거나 로그인을 대신 해 주지는 않습니다. `assistant_discovery: not_checked`는 호스트에서 직접 확인해야 한다는 뜻입니다. 필요하면 스킬을 새로 고치거나 새 대화를 여세요. [스킬 인식](https://evolink.ai/docs/ko/cli/billing.md#skills-discovery)을 참고하세요.

**5. 무료로 검증하고 준비 상태 확인**

```bash theme={null}
evolink balance --json
evolink doctor --json
```

**성공 표시**: balance가 계정 데이터를 반환하고, doctor가 `ok`, `connection_verified`, `model_discovery_verified`를 `true`로 보고하며, 에이전트가 스킬을 읽었다고 확인합니다. 잔액이 없어도 연결은 확인할 수 있지만, 생성하려면 잔액이 충분해야 합니다.

이 단계들은 유료 미디어 작업을 만들지 않습니다. 모두 완료되면 어시스턴트가 준비되었다고 알려 줄 수 있습니다. `failed`로 나온 검사가 있으면 진행하기 전에 해결하세요. 연결 테스트 삼아 이미지를 생성하지 마세요.

### 에이전트 하나에만 스킬 설치하기

웹사이트의 `evolink skills install`은 지원되는 모든 디렉토리에 설치합니다. 호스트 하나에만 설치하려면 아래의 `AGENT_NAME`을 이 표의 값으로 바꾸세요:

| 클라이언트 | AGENT\_NAME | 스킬 디렉토리 |
| - | - | - |
| Codex CLI | `codex` | `~/.agents/skills/evolink-cli` |
| Claude Code | `claude-code` | `~/.claude/skills/evolink-cli` |
| Cursor | `cursor` | `~/.agents/skills/evolink-cli` |
| OpenClaw | `openclaw` | `~/.openclaw/skills/evolink-cli` |
| Hermes | `hermes` | `~/.hermes/skills/evolink-cli` |
| Gemini CLI | `gemini` | `~/.agents/skills/evolink-cli` |
| OpenCode | `opencode` | `~/.agents/skills/evolink-cli` |
| GitHub Copilot CLI | `copilot` | `~/.agents/skills/evolink-cli` |

```text theme={null}
evolink skills install --agent AGENT_NAME
evolink doctor --agent AGENT_NAME --json
```

예를 들어 Gemini는 다음을 사용합니다:

```bash theme={null}
evolink skills install --agent gemini
evolink doctor --agent gemini --json
```

이 값들은 CLI의 설치 대상일 뿐, 모든 호스트 버전이 해당 디렉토리를 자동으로 인식한다는 보장은 아닙니다. 호스트가 명령 실행을 허용하고 스킬을 로드해야 합니다. [스킬 및 권한 문제 해결](https://evolink.ai/docs/ko/cli/billing.md#skills-discovery)을 참고하세요. 표에 없는 어시스턴트는 [에이전트가 읽을 수 있는 자료](https://evolink.ai/docs/ko/cli/skills.md)를 읽으면 됩니다. agent 값을 지어내지 마세요.

### CLI와 스킬 업데이트

```bash theme={null}
npm install -g @evolinkai/cli@latest
evolink --version
evolink skills install
evolink skills status --json
```

`current: true`를 확인하고 에이전트에게 스킬을 다시 읽으라고 요청하세요. 로컬에서 수정한 내용은 유지됩니다. `--replace-modified`는 수정한 내용을 교체하기로 결정한 뒤에만 사용하세요. 이전 내용은 `~/.evolink-media/skill-backups/` 아래에 백업됩니다. 새로 설치할 때는 예전의 `@evolinkai/media-cli` / `evolink-media`를 사용하지 마세요.

### 새 버전이 나왔는지 확인하는 방법

CLI 0.10.0부터는 CLI가 npm에서 최신 릴리스를 직접 확인합니다:

* `evolink setup`, `doctor`, `auth login`은 실행할 때마다 확인하고 `update`에 `update_available`, `latest_version`, 업그레이드 명령을 담아 보고합니다. 업데이트가 있다는 것은 알림일 뿐이며, 그 때문에 명령이 실패하지는 않습니다.
* 오프라인으로 동작하는 `auth status`를 제외한 다른 명령은 하루에 한 번까지만 온라인으로 확인합니다. 더 새로운 릴리스가 있으면 자체 출력 뒤에 stderr로 한 줄을 출력하며, 같은 릴리스에 대해서는 하루에 한 번까지만 출력합니다. `--json` stdout과 종료 코드는 바뀌지 않습니다.
* 확인할 때는 계정 정보가 없는 요청 하나를 공개 npm 레지스트리(registry.npmjs.org)로 보내고, 최대 3초까지 기다리며, 레지스트리에 연결할 수 없으면 아무것도 출력하지 않습니다.
* 확인을 끄려면 `EVOLINK_CLI_UPDATE_CHECK=0`을 설정하세요. `NO_UPDATE_NOTIFIER`에 아무 값이나 설정되어 있을 때와 CI 환경에서도 확인이 꺼집니다.

알림은 한 줄입니다:

```text theme={null}
EvoLink CLI 0.10.1 is available (installed 0.10.0). Update with npm install -g @evolinkai/cli@latest, then run evolink skills install.
```

이 알림이 보이면 위의 명령으로 업그레이드하고 스킬을 동기화하세요. 0.10.0 이전 버전은 알려 주지 않습니다. `evolink --version`과 `npm view @evolinkai/cli version`의 결과를 비교하거나, [CLI의 GitHub Releases](https://github.com/deeplearning-goethe/evolink-cli/releases) 페이지를 열고 Watch → Custom → Releases를 선택해 구독하세요.

브라우저 승인이 사이트로 돌아오지 않고 두 언어로 표시된 127.0.0.1 페이지에서 끝난다면, 설치된 CLI가 0.9.1보다 오래된 버전입니다. 계속하기 전에 업그레이드하세요.

### 로그인 상태 확인 또는 로그아웃

현재 세션을 확인합니다:

```bash theme={null}
evolink auth status --json
```

로그아웃하려는 경우에만 다음을 따로 실행하세요:

```bash theme={null}
evolink auth logout
```

이 명령은 현재 CLI 세션을 폐기합니다. 네이티브 MCP 인증은 해당 호스트에서 관리하세요. 계정을 전환하기 전에 기존 작업 ID를 저장해 두세요. 이전 견적은 새 계정으로 제출할 수 없습니다.

### Linux와 SSH: 브라우저가 다른 컴퓨터에 있는 경우

Linux에서 로그인을 유지하려면 현재 사용자 세션에 **D-Bus와 잠금 해제된 Secret Service**가 필요합니다. 이것부터 확인하세요. 없으면 `credential_store_unavailable`이 나오는 것이 정상이며, root 권한으로 대신할 수 없습니다. 보안 저장소를 설정하거나, 보안 저장소가 제공되는 환경에서 CLI를 로컬로 실행하세요.

**1. 원격 호스트에서 로그인 시작**

```bash theme={null}
evolink auth login --no-browser --timeout 600
```

이 명령을 실행 중인 상태로 두고 현재 인증 링크를 사용하세요. `--no-browser`는 브라우저를 열지 않을 뿐 콜백은 그대로 기다립니다. **디바이스 코드 로그인이 아닙니다**. 범위는 30–900초이고 기본값은 180초입니다.

**2. 로컬 터미널에서 콜백 포트 포워딩**

이번 로그인 시도의 `redirect_uri`에서 실제 포트를 찾으세요. 두 곳의 `CALLBACK_PORT` 값과 `USER`, `HOST`를 바꾸세요. `http://127.0.0.1:54321/callback`이라면 두 위치 모두에 `54321`을 사용합니다. 전체 인증 링크를 공개하지 마세요.

```bash theme={null}
ssh -N -L CALLBACK_PORT:127.0.0.1:CALLBACK_PORT USER@HOST
```

포워딩용 터미널은 실행 중인 상태로 두세요. 프롬프트 없이 멈춰 있는 것처럼 보여도 정상입니다. 포트가 충돌하면 인증 링크의 포트를 수정하지 말고 충돌을 해결하세요.

**3. 링크를 열고 원격에서 검증**

첫 단계의 링크를 로컬 브라우저에서 열고 로그인한 뒤 승인하고, 원격 명령이 끝날 때까지 기다리세요. 같은 원격 사용자 환경에서 다음을 실행하세요:

```bash theme={null}
evolink auth status --json
evolink balance --json
```

성공하면 이 포워딩 세션을 종료하세요. 시간이 초과되면 로그인을 새로 시작하고 그 로그인의 실제 포트를 포워딩하세요. 이전 링크는 다시 쓸 수 없습니다. 네이티브 MCP 콜백은 호스트가 처리하며 EvoLink CLI 옵션을 사용하지 않습니다.

## 설치 후

[첫 생성 작업 흐름](https://evolink.ai/docs/ko/cli/workflows.md#workflows)을 따르세요. 작업을 설명하고, 에이전트가 사용할 수 있는 모델, 매개변수, 비용을 확인하게 한 뒤, 제출하기 전에 확인하세요. 설치, 로그인, 권한, 다운로드에 관해서는 [CLI 명령 레퍼런스](https://evolink.ai/docs/ko/cli/reference.md#cli-reference)와 [통합 문제 해결](https://evolink.ai/docs/ko/cli/billing.md#faq)을 참고하세요.

네이티브 원격 MCP나 로컬 stdio를 쓰려면 [다른 MCP 클라이언트 가이드](https://evolink.ai/docs/ko/mcp/other-clients.md)를 이용하세요. CLI 로그인 옵션으로는 MCP 연결이 설정되지 않습니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.