---
title: "명령 실행하기"
description: "승인받은 작업 세션과 계정으로 Alpacon 명령어를 실행합니다. 목적을 전달하고 시크릿은 환경 변수로 넘기는 방법을 알아보세요. 오래 걸리는 작업은 detach로 제출한 뒤 같은 작업의 결과를 조회하고, 승인 대기와 실행 시간 초과, CLI 대기 종료를 구분해 중복 실행을 피하세요."
---

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

# 명령 실행하기

`alpacon login`으로 로그인했다면 아래 절차를 따르세요. 서비스 토큰을 쓰는 자동화 작업은 [서비스 토큰](/use/iam/applications/service-tokens/)을 참고하세요.

### 작업 세션 요청

대상 서버와 명령 실행 기능(`command`)을 포함해 [작업 세션을 요청](/use/work-sessions/create/)하세요. 세션이 **활성** 상태가 될 때까지 기다리세요.

### 작업 세션 연결

CLI 워크스페이스에서 쓸 세션을 지정하세요.

```bash
alpacon work-session use WORK_SESSION_ID
```

각 명령어에 `--work-session WORK_SESSION_ID`를 전달해도 됩니다. AI 에이전트는 에이전트 작업 세션을 쓰고, 세션 ID를 명시적으로 전달해야 합니다.

### 명령어 실행

```bash
alpacon exec --purpose "Check disk space before deployment" my-server -- df -h
```

exec 플래그는 서버 이름 앞에 놓으세요. CLI는 서버 이름 뒤의 모든 인수를 원격 명령어로 해석합니다. `--`로 경계를 명확히 표시할 수 있습니다. 결과는 CLI 또는 [**명령 기록**](/use/audit/events/commands/)에서 확인하세요.

## 실행 계정 선택

`USER@SERVER` 또는 `-u USER`로 서버 계정을 지정하세요.

```bash
alpacon exec admin@my-server -- whoami
alpacon exec -u admin my-server -- whoami
```

세션에서 허용하는 계정을 쓰세요. 에이전트 세션은 승인받은 계정으로만 실행할 수 있으며, 다른 계정을 선택하면 거부됩니다. [계정 선택](/use/work-sessions/account-selection/)을 참고하세요.

## 실행 목적 전달

`--purpose`는 명령어와 함께 실행 맥락을 전달합니다. 이 서버에서 해당 작업이 필요한 이유를 적으세요. 최대 2000자이며, 이를 넘으면 거부됩니다. 감사 기록의 상세 패널에서 **요청자가 밝힌 목적** 항목으로 확인할 수 있습니다.

워크스페이스에서 목적을 요청하는 경우, 명령어가 **목적 확인 중** 상태로 대기하고 CLI는 종료 코드 7로 끝날 수 있습니다. 같은 작업에 목적을 전달하세요.

```bash
alpacon exec purpose JOB_ID "Check disk space before deployment"
```

응답할 수 있는 시간과 이후 동작은 [`exec purpose`](/reference/cli/exec/#exec-purpose)를 참고하세요.

## 시크릿을 환경 변수로 전달

자격 증명을 명령줄에 넣지 마세요. 로컬 셸에 `PGPASSWORD`가 설정되어 있다면 변수 이름만 전달하세요.

```bash
alpacon exec --env="PGPASSWORD" db-server -- psql -h localhost -U app -c 'SELECT 1'
```

CLI가 로컬 환경에서 값을 읽습니다. 원격 명령어에서 이 변수를 출력하지 마세요. 자격 증명이 명령줄에 포함되면 실행이 거부됩니다. `--env`는 명령줄 실행에 쓰는 옵션이며 `--file`과 함께 쓸 수 없습니다.

## 오래 걸리는 명령어

약 10분을 넘길 수 있는 작업은 `--detach`로 제출하세요.

```bash
alpacon exec --detach --purpose "Refresh package metadata" my-server -- apt-get update
alpacon exec logs JOB_ID
```

제출하면 `Job submitted: `가 출력됩니다. 결과를 조회할 때는 `JOB_ID`를 출력된 UUID로 바꾸세요. 포그라운드 `alpacon exec`는 수신 확인 또는 전달 후 10분 동안 결과가 없으면 응답 없음으로 판단하고 종료 코드 1로 끝납니다. 서버에서는 명령어가 최대 30분까지 계속 실행되므로, CLI가 대기를 끝냈다는 이유로 같은 작업을 다시 제출하지 마세요.

| `exec logs` 조회 결과 | 종료 코드 | 다음 조치 |
| --- | --- | --- |
| 실행 중 또는 실행 대기 중 | 0 | 나중에 같은 작업을 다시 조회. 코드 0만으로 완료를 판단하지 않음 |
| 워크스페이스에서 목적을 요청해 대기 중 | 7 | `alpacon exec purpose JOB_ID PURPOSE`로 목적 전달 |
| 승인 대기 | 4 | 승인자에게 콘솔에서 결정을 요청 |
| 반려됨 | 6 | 다른 명령어를 제출하기 전에 사유 확인 |
| 응답 없음, 오류 또는 취소됨 | 1 | **명령 기록**에서 상태와 상세 정보 확인 |
| 실행 완료 | 원격 명령어의 종료 코드 | 출력과 종료 코드 확인 |

서버에서 명령어를 실행할 수 있는 시간은 최대 30분입니다. 제한에 도달하면 종료 코드 124와 `Command timed out after 30m0s`가 반환됩니다. 더 긴 작업은 각각 제한 안에 끝나도록 나누세요.

### ALPACON_EXEC_TIMEOUT

`ALPACON_EXEC_TIMEOUT`은 CLI가 실행 중 상태를 받지 못할 때 기다리는 시간을 정합니다. 기본값은 `30m`이며 `1h` 같은 기간을 지정할 수 있습니다. 진행 중 상태를 받을 때마다 대기 시간이 다시 시작됩니다. 이 값으로 서버의 실행 시간 제한을 늘리거나 포그라운드 실행의 응답 없음 판정을 막을 수는 없습니다.

대기 시간이 지나면 CLI는 `Error: [client_timeout] CLI gave up waiting for the server to report a result`를 출력하고 종료 코드 1로 끝납니다. 명령어는 취소되지 않습니다. 다시 실행할지 결정하기 전에 `alpacon exec logs JOB_ID`로 확인하세요.

## 승인 대기

**승인 대기** 상태의 명령어는 콘솔에서 사람의 결정을 기다립니다. `--wait` 또는 `--wait-approval 30m`으로 기다리지 않으면 CLI는 종료 코드 4로 끝납니다. 기본 승인 대기 시간은 5분입니다. 보류된 명령어는 승인되면 자동으로 실행되므로, 기다리는 동안 다시 제출하지 마세요.

sudo 승인과 터미널 인증은 [sudo와 MFA](/use/work-sessions/terminal/sudo-with-mfa/)를 참고하세요. 명령어가 반려되면 재시도 전에 [**명령 기록**](/use/audit/events/commands/)의 **거절 이유** 항목을 확인하세요.

Source: https://docs.alpacax.com/ko/use/work-sessions/commands/run/