---
title: "CLI로 첫 명령 실행"
description: "Alpacon CLI를 설치하고 워크스페이스에 로그인한 뒤 시간 제한 작업 세션을 요청합니다. 등록된 서버에서 안전한 명령을 직접 실행해 보고 결과와 기록을 확인한 다음 세션을 완료하세요. 운영체제별 설치 방법과 Websh 접속, 로그아웃 절차도 함께 익힐 수 있습니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# CLI로 첫 명령 실행

<span id="시작하기" />
# CLI로 첫 명령 실행

**Alpacon CLI**로 터미널에서 Alpacon 작업을 할 수 있습니다. 이 튜토리얼에서는 CLI를 설치하고 로그인한 뒤 작업 세션을 요청해 `whoami`를 실행하고 세션을 완료합니다. 접근 권한이 있는 서버를 사용하세요.

## 1. 사전 준비사항

다음 조건을 충족했는지 먼저 확인하세요:

- 워크스페이스 초대와 에이전트가 온라인 상태인 등록 서버가 필요합니다. 서버를 아직 등록하지 않았다면 [Alpamon 설치](/use/servers/register/install/)를 참고하세요.

## 2. 설치

Alpacon CLI는 운영체제별로 다양한 방법으로 설치할 수 있습니다. 아래에서 사용하는 환경에 맞는 탭을 선택하여 설치를 진행하세요.

**AI에게 맡기고 싶다면?** 아래 프롬프트를 Claude, Cursor 등 AI 도구에 복사해 붙여넣으세요. 사용자의 기기에서 실행되는 어시스턴트(예: Claude Code)는 OS를 자동으로 감지해 단계를 실행할 수 있고, 채팅에서는 사용하는 OS만 알려주면 됩니다.

```text
내 기기에 Alpacon CLI를 설치해줘. 공식 가이드(https://docs.alpacax.com/learn/tutorials/cli/)의 설치 단계를 따라, 내 OS(Linux, macOS, Windows)를 감지하거나 내가 알려주는 OS를 기준으로 실행하고, 끝나면 `alpacon version`으로 확인해줘.
```

  
    #### Ubuntu / Debian

    ```bash
    curl -s https://packagecloud.io/install/repositories/alpacax/alpacon/script.deb.sh?any=true | sudo bash
    sudo apt-get install alpacon
    ```

    #### CentOS / RHEL

    ```bash
    curl -s https://packagecloud.io/install/repositories/alpacax/alpacon/script.rpm.sh?any=true | sudo bash
    sudo yum install alpacon
    ```

    #### GitHub Releases

    ```bash
    VERSION=<최신버전>
    wget https://github.com/alpacax/alpacon-cli/releases/download/${VERSION}/alpacon-${VERSION}-linux-amd64.tar.gz
    tar -xvf alpacon-${VERSION}-linux-amd64.tar.gz
    chmod +x alpacon
    sudo mv alpacon /usr/local/bin
    ```

  

  
    #### Homebrew

    ```bash
    brew install alpacax/alpacon/alpacon-cli
    ```

    #### GitHub Releases

    ```bash
    VERSION=<최신버전>
    wget https://github.com/alpacax/alpacon-cli/releases/download/${VERSION}/alpacon-${VERSION}-darwin-arm64.tar.gz
    tar -xvf alpacon-${VERSION}-darwin-arm64.tar.gz
    chmod +x alpacon
    sudo mv alpacon /usr/local/bin
    ```

  

  
    Docker를 사용하는 경우 설치 없이 바로 CLI를 실행할 수 있습니다.

    ```bash
    docker run --rm -it alpacax/alpacon-cli version
    ```

  

  
    Go가 설치되어 있어야 합니다.

    ```bash
    git clone https://github.com/alpacax/alpacon-cli.git
    cd alpacon-cli
    go build
    sudo mv alpacon-cli /usr/local/bin/alpacon
    ```

  

  
    #### GitHub Releases

    최신 Windows 빌드를 내려받아 압축을 풀고 `PATH`에 추가합니다. **PowerShell**에서:

    ```powershell
    # Pick the version from the Releases page (use windows-arm64 on ARM devices)
    $Version = "<최신버전>"
    $Dest = "$env:LOCALAPPDATA\Alpacon"

    Invoke-WebRequest -UseBasicParsing `
      -Uri "https://github.com/alpacax/alpacon-cli/releases/download/$Version/alpacon-$Version-windows-amd64.zip" `
      -OutFile "$env:TEMP\alpacon.zip"
    Expand-Archive -Path "$env:TEMP\alpacon.zip" -DestinationPath $Dest -Force

    # Add alpacon to your PATH (current user)
    [Environment]::SetEnvironmentVariable(
      "Path", "$([Environment]::GetEnvironmentVariable('Path','User'));$Dest", "User")
    ```

    `PATH` 변경이 적용되도록 **새** 터미널(PowerShell 또는 Windows Terminal)을 연 뒤 확인합니다:

    ```powershell
    alpacon version
    ```

    명령어는 Linux, macOS와 동일하게 동작합니다. 로그인 설정은 `%USERPROFILE%\.alpacon\config.json`에 저장됩니다.
  

---

각 설치 방법에 대한 최신 정보는 [공식 GitHub 저장소](https://github.com/alpacax/alpacon-cli)를 참고하세요.

## 3. 로그인 및 로그아웃

Alpacon CLI의 모든 기능을 사용하려면 먼저 Alpacon API에 인증해야 합니다.

### 로그인

**Alpacon Cloud**는 워크스페이스 이름과 리전으로 로그인하거나, 인자 없이 `alpacon login`을 실행하여 대화형으로 입력할 수 있습니다. **자체 호스팅**(Self-hosted)은 호스트를 인자로 전달합니다.

```bash
# Alpacon Cloud (interactive)
alpacon login

# Alpacon Cloud (non-interactive)
alpacon login --workspace myworkspace --region ap1

# Alpacon Cloud with an API token
alpacon login --workspace myworkspace --region ap1 -t apikey1234

# Self-hosted
alpacon login alpacon.example.com
```

Alpacon Cloud 브라우저 로그인(API 토큰을 사용하지 않는 경우)은 브라우저를 통해 인증이 진행됩니다. CLI에 표시되는 URL을 브라우저에서 열어주세요:

```
Logging in to https://myworkspace.ap1.alpacon.io

==================== AUTHENTICATION REQUIRED ====================

Please authenticate by visiting the following URL:
https://auth.alpacon.io/activate?user_code=BBHT-GNKB

===============================================================
```

해당 링크를 브라우저에서 열어 인증을 완료하세요 (워크스페이스에 MFA가 설정된 경우 MFA 인증도 포함됩니다).

### 재로그인

재로그인 시 `config.json`에 저장된 **기존 워크스페이스 URL**이 자동으로 재사용됩니다:

```bash
alpacon login  # Uses saved workspace URL
```

다른 워크스페이스로 로그인하려면 명령어에 `--workspace`와 `--region`(Alpacon Cloud) 또는 새로운 호스트(자체 호스팅)를 지정하세요.

### 워크스페이스 관리

Auth0를 통해 로그인한 경우, 재인증 없이 워크스페이스를 조회하고 전환할 수 있습니다:

```bash
# 현재 워크스페이스 확인
alpacon workspace

# 사용 가능한 워크스페이스 목록 조회
alpacon workspace ls

# 다른 워크스페이스로 전환
alpacon workspace switch other-workspace
```

워크스페이스 전환은 리전 간에도 가능합니다 (예: `us1`에서 `ap1`으로). 워크스페이스 목록은 로그인 토큰에서 추출되며, 별도의 API 호출이 필요하지 않습니다.

### 로그아웃

```bash
alpacon logout
```

> 멀티 워크스페이스 모드인 경우, 로그아웃하면 계정에 연결된 **모든 워크스페이스**의 세션이 종료됩니다.

### config.json

로그인에 성공하면 다음 경로에 설정 파일이 자동으로 생성됩니다:

```
~/.alpacon/config.json              # Linux, macOS
%USERPROFILE%\.alpacon\config.json  # Windows
```

이 파일에는 다음 정보가 포함됩니다:

- 워크스페이스 URL 및 이름
- 인증 토큰
- 베이스 도메인 (멀티 워크스페이스 지원용)

해당 파일은 Alpacon CLI가 명령어를 실행할 때 필수적으로 사용되며, 토큰이 만료되면 다시 로그인해야 합니다.

_`alpacon logout` 명령을 실행하면 이 `config.json` 파일은 삭제되며, 이후 명령어 실행을 위해 다시 로그인이 필요합니다._

## 4. 서버 목록 조회

워크스페이스에 등록된 서버 목록을 확인하려면 다음 명령어를 실행하세요.

```bash
alpacon server ls
alpacon server list
```

## 5. 작업 세션 생성

브라우저 로그인으로 인증한 경우, `websh`, `exec`, `cp`, `tunnel` 같은 접근 명령을 실행하려면 활성 작업 세션이 필요합니다. 세션을 요청하고 관리하는 방법은 [alpacon work-session](/reference/cli/work-session/)을 참고하세요. 토큰 인증의 예외는 비대화형 `exec`, `cp`, `edit`, `websh SERVER "command"`에만 적용됩니다. 토큰으로는 대화형 Websh나 터널을 열 수 없으므로, 이 작업에는 `-t` 없이 `alpacon login`으로 로그인하세요.

새 개인 API 토큰에는 명령어 실행이나 파일 전송 범위를 부여할 수 없습니다. 해당 범위를 이미 가진 토큰은 작업 세션 없이 계속 사용할 수 있습니다. 자동화와 CI에는 [서비스 토큰](/use/iam/applications/service-tokens/)을 쓰세요.

현재 인증에 작업 세션이 필요한지 확인하세요.

```bash
alpacon whoami
```

필요하다면 세션 생성, 승인 대기, 활성 세션 지정을 한 번에 처리하세요.

```bash
alpacon work-session create --purpose "server check" --scope command,websh \
  --server my-server --expires-in 1h --wait --use
```

이후 접근 명령은 이 세션에 자동으로 연결됩니다. 전체 워크플로는 [alpacon work-session](/reference/cli/work-session/) 레퍼런스를 참고하세요.

## 6. 명령 실행과 결과 확인

선택한 서버에서 안전한 명령을 실행합니다. 활성 작업 세션이 자동으로 연결됩니다.

```bash
alpacon exec my-server -- whoami
```

명령 결과를 확인하고 [Session history](/use/audit/sessions/)에서 세션 기록을 검토하세요.

<span id="6-websh-접속" />

## 7. Websh 접속

서버의 Websh 터미널에 접속하려면 다음 명령어를 사용하세요.

`CONNECTED` 상태가 **true**인 서버만 접속할 수 있습니다.

### 기본 접속

```bash
alpacon websh my-server
```

### root 권한으로 접속

워크스페이스에서 root 직접 접속을 허용하고 작업 세션에 해당 계정이 포함되어 있다면 **root** 권한으로 접속할 수 있습니다.

```bash
alpacon websh root@my-server
```

### 접속 종료

```bash
exit
```

작업이 끝나면 작업 세션을 생성할 때 출력된 ID로 세션을 완료하세요.

```bash
alpacon work-session complete SESSION_ID
```

## 더 알아보기

이제 Alpacon CLI의 기본 사용법을 익히셨습니다.  
필요한 명령의 인자와 옵션은 [CLI 참조](/reference/cli/)에서 확인하세요.

Source: https://docs.alpacax.com/ko/learn/tutorials/cli/