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

# vesslctl 이해하기

> VESSL Cloud 커맨드라인 도구를 설치하고 설정하는 방법을 알아봐요.

`vesslctl`은 VESSL Cloud의 커맨드라인 인터페이스예요. 터미널에서 Workspace, Batch Job, Storage, 팀 설정 등을 관리할 수 있어요.

### 왜 `vesslctl`인가요?

* **개발과 학습을 하나의 도구로**: 인터랙티브 Workspace에서 개발하고, Batch Job으로 학습을 실행하는 걸 같은 CLI에서 할 수 있어요.
* **팀을 위해 만들어졌어요**: 조직과 팀 범위 지정으로 워크로드, Volume, 과금이 필요한 곳에서 격리돼요.
* **스토리지 선택이 자유로워요**: 클러스터 간 접근이 필요하면 Object storage, 고성능 로컬 I/O가 필요하면 Cluster storage를 선택하고, 어떤 워크로드에든 Volume을 마운트할 수 있어요.
* **AI 네이티브**: VESSL Cloud docs를 Claude Code, Cursor 등 MCP 호환 도구에 연결하면 AI 어시스턴트가 정확한 CLI 문서를 참조해요. [AI 도구와 함께 사용하기](/ko/cli/ai-tools)를 확인하세요.
* **스크립트 친화적**: 셸 스크립트로 명령어를 조합해서 하이퍼파라미터 탐색, 데이터 파이프라인, 자율 실험 루프를 만들 수 있어요.

## 설치

<Info>
  **지원 환경**: macOS 15 이상, Ubuntu 20.04 이상, Windows 10 이상. 그 외 별도 환경 의존성은 없어요.
</Info>

<Steps>
  <Step title="vesslctl 설치">
    ```bash theme={null}
    curl -fsSL https://api.cloud.vessl.ai/cli/install.sh | bash
    ```
  </Step>

  <Step title="로그인">
    ```bash theme={null}
    vesslctl auth login
    ```

    브라우저에서 OAuth 인증 페이지가 열려요. 브라우저를 사용할 수 없는 환경에서는 이메일/비밀번호 로그인으로 전환돼요.
  </Step>

  <Step title="설치 확인">
    ```bash theme={null}
    vesslctl auth status
    ```
  </Step>
</Steps>

## 글로벌 플래그

모든 명령어에서 사용할 수 있는 플래그예요:

| 플래그        | 약어   | 설명                                     |
| ---------- | ---- | -------------------------------------- |
| `--org`    |      | 기본 조직을 오버라이드해요.                        |
| `--team`   | `-t` | 기본 팀을 오버라이드해요.                         |
| `--output` | `-o` | 출력 형식: `table` (기본값), `json`, 또는 `csv` |

## 기본값 설정

로그인하면 `vesslctl`이 기본 조직과 팀을 선택하라고 안내해요. 언제든 변경할 수 있어요:

```bash theme={null}
vesslctl config set default_org <your-org>
vesslctl config set default_team <your-team>
```

현재 설정을 확인하려면:

```bash theme={null}
vesslctl config show
```

## 환경 변수

`vesslctl`은 아래 환경 변수를 읽어요. 플래그가 환경 변수보다 우선하고, 환경 변수가 설정 파일보다 우선해요:

| 변수                             | 설명                                                                                                           |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `VESSLCTL_ORG`                 | 기본 조직(설정 파일의 `default_org`를 오버라이드)                                                                           |
| `VESSLCTL_TEAM`                | 기본 팀(설정 파일의 `default_team`을 오버라이드)                                                                           |
| `VESSLCTL_OUTPUT`              | 기본 출력 형식: `table`, `json`, 또는 `csv`                                                                          |
| `VESSLCTL_API_URL`             | API 엔드포인트 오버라이드(기본값은 프로덕션 URL)                                                                               |
| `VESSLCTL_ACCESS_TOKEN`        | 장기 액세스 토큰. 설정되면 `vesslctl`이 인터랙티브 로그인 단계를 건너뛰어요.                                                             |
| `SIDECAR_INITIAL_ACCESS_TOKEN` | VESSL Cloud Workspace 내부에 자동 주입돼서 로그인 없이 `vesslctl`을 실행할 수 있게 해 줘요. `VESSLCTL_ACCESS_TOKEN`이 없을 때 폴백으로 사용돼요. |

<Tip>
  VESSL Cloud Workspace 내부에서는 `vesslctl`이 `SIDECAR_INITIAL_ACCESS_TOKEN`으로 미리 인증돼 있어요. `vesslctl auth status`로 확인해 보세요. Workspace 터미널에서는 `vesslctl auth login`을 따로 실행하지 않아도 돼요.
</Tip>

## 셸 자동완성

탭 자동완성을 켜는 가장 쉬운 방법은 `install` 서브커맨드예요. 셸을 자동으로 감지하고 적절한 위치에 스크립트를 설치해 줘요:

```bash theme={null}
vesslctl completion install
```

멱등성이 보장돼서 CLI 업데이트 후 다시 실행해도 안전해요. zsh를 쓰면 `~/.zshrc`에 `fpath` 설정이 필요한 경우 안내 메시지를 띄워 줘요.

<Accordion title="수동 설정">
  직접 completion 스크립트를 관리하고 싶다면:

  <CodeGroup>
    ```bash Bash theme={null}
    vesslctl completion bash > /etc/bash_completion.d/vesslctl
    ```

    ```bash Zsh theme={null}
    vesslctl completion zsh > "${fpath[1]}/_vesslctl"
    ```

    ```bash Fish theme={null}
    vesslctl completion fish > ~/.config/fish/completions/vesslctl.fish
    ```
  </CodeGroup>
</Accordion>

## 업데이트

`vesslctl`을 최신 버전으로 유지하세요:

```bash theme={null}
vesslctl update
```

## 명령어 개요

| 명령어                                          | 설명                                                                     |
| -------------------------------------------- | ---------------------------------------------------------------------- |
| [`workspace`](/ko/cli/commands/workspace)    | GPU Workspace 관리(생성, SSH, 일시정지, 종료)                                    |
| [`job`](/ko/cli/commands/job)                | Batch Job 제출 및 관리                                                      |
| [`volume`](/ko/cli/commands/volume)          | Storage Volume 관리                                                      |
| [`storage`](/ko/cli/commands/storage)        | 저장소 조회 및 관리                                                            |
| [`org`](/ko/cli/commands/org-team)           | 조직 전환 및 관리                                                             |
| [`team`](/ko/cli/commands/org-team)          | 팀 전환 및 관리                                                              |
| [`cluster`](/ko/cli/commands/cluster)        | 클러스터 조회                                                                |
| [`resource-spec`](/ko/cli/commands/cluster)  | GPU/CPU 리소스 설정 조회(별칭: `rs`)                                            |
| [`tag`](/ko/cli/commands/tag)                | Job에 달 태그 생성·조회·관리                                                     |
| [`skill`](/ko/cli/commands/skill)            | AI 코딩 에이전트용 vesslctl 스킬 설치                                             |
| [`config`](/ko/cli/commands/config)          | CLI 설정 및 인증 관리                                                         |
| [`auth`](/ko/cli/commands/config)            | 로그인, 로그아웃, 인증 상태 확인                                                    |
| [`billing`](/ko/cli/commands/config)         | 크레딧 잔액과 소모율 조회                                                         |
| [`completion`](/ko/cli/commands/completion)  | 셸 탭 자동완성. `install`로 자동 설정하거나 bash, zsh, fish, PowerShell용 스크립트를 직접 생성 |
| [`update`](/ko/cli/commands/update)          | `vesslctl` 최신 버전으로 업데이트                                                |
| [`install`](/ko/cli/commands/config#install) | `vesslctl`을 PATH 디렉터리에 설치                                              |