Ocean CLI 설치와 설정¶
oceanctl을 사용하면 터미널에서 프로젝트와 할당량을 확인하고, 인스턴스와 잡을 실행하거나 상태를 조회할 수 있습니다.
언제 쓰나요¶
다음 작업을 터미널이나 자동화 도구에서 반복할 때 사용합니다.
프로젝트와 남은 할당량 확인
사용 가능한 이미지, 볼륨, 노드 확인
인스턴스 생성과 조회
잡 제출, 대기, 로그 확인
CLI 4.x의 워크로드 생성은 CPU·메모리·GPU 총량 할당량 모드를 기준으로 합니다. 웹 생성 화면에 CPU·메모리·GPU 입력란 대신 머신타입 선택기가 보인다면 인스턴스와 잡은 웹에서 만드세요.
1. 설치하기¶
CLI 애플리케이션을 시스템 Python과 분리해 설치할 수 있는 uv를 권장합니다. uv가 없다면 uv 공식 설치 안내를 먼저 확인하세요.
uv tool install oceanctl
oceanctl --version
설치하지 않고 한 번만 실행하려면 uvx를 사용할 수 있습니다.
uvx oceanctl --version
pipx로 설치하기¶
이미 pipx를 사용하고 있다면 다음과 같이 설치해도 됩니다. oceanctl은 Python 3.10 이상이 필요하므로, 설치가 Python 버전 오류로 실패하면 python3 --version으로 확인하고 Python 3.10 이상 환경에서 다시 설치하세요.
pipx install oceanctl
oceanctl --version
경고
pip install --break-system-packages는 사용하지 마세요. 시스템 Python을 변경하지 않고 uv tool 또는 pipx로 격리해 설치하는 편이 안전합니다.
2. CLI 토큰 발급하기¶
AIOcean 콘솔에 로그인하고 사용할 조직을 선택합니다.
사이드바에서 CLI 토큰을 엽니다.
토큰 발급을 누릅니다.
알아보기 쉬운 이름을 입력하고 사용할 클러스터를 선택한 뒤 발급하기를 누릅니다.
화면에 한 번만 표시되는 토큰을 복사합니다.
토큰은 발급할 때 선택한 조직과 클러스터에 연결됩니다. 다른 클러스터를 사용하려면 해당 클러스터용 토큰을 따로 발급해야 합니다.
3. 연결 설정하기¶
다음 명령을 실행하고, 프롬프트가 나타나면 복사한 CLI 토큰을 붙여 넣으세요. 토큰은 입력할 때 화면에 표시되지 않습니다.
oceanctl configure --api-url https://api.aiocean.click
설정이 저장됐는지 확인합니다.
oceanctl configure --show
자격증명은 기본적으로 ~/.ocean/credentials에 저장되며 파일 권한은 0600으로 설정됩니다.
경고
CLI 토큰은 자동으로 만료되지 않으며 웹에서 폐기할 때까지 유효합니다. 토큰을 명령줄 옵션이나 환경변수로 넘기지 마세요. 셸 기록, 프로세스 목록 또는 로그에 남을 수 있습니다. 공유 인스턴스에는 자격증명 파일을 두지 말고, 사용이 끝난 토큰은 웹 콘솔의 CLI 토큰 화면에서 폐기하세요.
4. 연결 확인하기¶
먼저 현재 사용자·조직·클러스터를 확인합니다.
oceanctl whoami
이어서 기본 프로젝트의 남은 할당량을 확인합니다.
oceanctl quota
두 명령이 정상적으로 정보를 표시하면 설치와 연결 설정이 완료된 것입니다. 프로젝트가 없다면 먼저 프로젝트 만들기를 진행하세요.
업데이트와 삭제¶
uv로 설치했다면 다음 명령을 사용합니다.
uv tool upgrade oceanctl
uv tool uninstall oceanctl
pipx로 설치했다면 다음 명령을 사용합니다.
pipx upgrade oceanctl
pipx uninstall oceanctl
문제가 생기면¶
oceanctl: command not found¶
uv 설치 경로가 셸의 PATH에 반영되지 않았을 수 있습니다.
uv tool update-shell
터미널을 다시 열고 oceanctl --version을 실행하세요.
토큰이 유효하지 않다고 나와요¶
웹 콘솔의 CLI 토큰 화면에서 토큰이 폐기되지 않았는지 확인하세요. 토큰을 다시 발급했다면 oceanctl configure를 다시 실행해야 합니다.
다른 조직이나 클러스터가 보여요¶
CLI 토큰은 조직과 클러스터에 연결됩니다. 원하는 조직의 CLI 토큰 화면에서 사용할 클러스터를 선택해 새 토큰을 발급한 뒤 다시 설정하세요.