CLI로 첫 명령 실행

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

1. 사전 준비사항

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

  • 워크스페이스 초대와 에이전트가 온라인 상태인 등록 서버가 필요합니다. 서버를 아직 등록하지 않았다면 Alpamon 설치를 참고하세요.

2. 설치

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

참고

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

내 기기에 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
팁

각 설치 방법에 대한 최신 정보는 공식 GitHub 저장소를 참고하세요.

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을 참고하세요. 토큰 인증의 예외는 비대화형 exec, cp, edit, websh SERVER "command"에만 적용됩니다. 토큰으로는 대화형 Websh나 터널을 열 수 없으므로, 이 작업에는 -t 없이 alpacon login으로 로그인하세요.

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

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

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 레퍼런스를 참고하세요.

6. 명령 실행과 결과 확인

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

bash
alpacon exec my-server -- whoami

명령 결과를 확인하고 Session history에서 세션 기록을 검토하세요.

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 참조에서 확인하세요.

최종 수정: