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

# Agent CLI

> 내 저장소에서 로컬 코딩 에이전트를 실행하고, CloudThinker Sandbox와 워크스페이스 승인을 통해 클라우드를 읽고 변경하세요

<Note>
  **미리 보기** — `cloudthinker agent`는 macOS와 Linux용 CloudThinker CLI에 포함되며 유료 워크스페이스 플랜이 필요합니다. 미리 보기 참여를 원하시면 [문의하기](https://cloudthinker.io/contact)를 클릭하세요.
</Note>

`cloudthinker agent`는 터미널에서 실행되는 코딩 에이전트이며 [pi](https://github.com/badlogic/pi-mono) 위에 만들어졌습니다. 파일 편집과 명령 실행은 내 컴퓨터에서 하고, 클라우드에는 워크스페이스 연결을 사용해 CloudThinker Sandbox를 통해서만 접근합니다.

## Agent CLI를 쓰는 이유

* **저장소는 로컬에 그대로.** 모델 루프, 파일 편집, 셸 명령이 모두 내 노트북에서 실행됩니다.
* **클라우드 자격 증명이 내 컴퓨터에 없음.** 클라우드 명령은 CloudThinker Sandbox에서 실행되며, 연결 자격 증명은 그 실행에만 주입됩니다.
* **워크스페이스 규칙이 그대로 적용됨.** 클라우드 쓰기는 채팅과 동일한 [Auto Mode](/ko/guide/auto-mode)와 승인 규칙을 따릅니다.
* **모든 세션이 미러링됨.** 팀원이 브라우저에서 세션을 읽을 수 있고, 워크스페이스가 감사와 과금을 처리합니다.

## 세션 시작하기

<Steps>
  <Step title="설치하고 로그인">
    [CloudThinker CLI](/ko/guide/cli/overview)를 설치하고 `cloudthinker login`을 실행하세요. 자격 증명이 없으면 에이전트가 브라우저 로그인을 대신 실행합니다.
  </Step>

  <Step title="저장소에서 에이전트 실행">
    ```bash theme={null}
    cd my-terraform-repo
    cloudthinker agent
    ```

    첫 실행에서 CLI가 해당 플랫폼용 에이전트 번들을 내려받고 체크섬을 검증합니다.
  </Step>

  <Step title="헤더 확인">
    헤더에는 워크스페이스, 사용자, 세션 링크, 그리고 워크스페이스 승인 모드가 `· Auto` 또는 `· Manual`로 표시됩니다.

    **성공 상태:** 푸터에 `◆ 0.00 credits`가 보이고 첫 프롬프트를 입력할 수 있습니다.
  </Step>
</Steps>

## 두 가지 실행 환경

에이전트는 정확히 두 곳에서만 동작하며, 어느 쪽을 쓰는지 항상 알려줍니다.

| 환경                       | 그곳에서 실행되는 것                                        | 자격 증명                                         |
| ------------------------ | -------------------------------------------------- | --------------------------------------------- |
| **내 컴퓨터**                | pi의 로컬 도구: bash, read, write, edit, grep, find, ls | CloudThinker 자격 증명 없음                         |
| **CloudThinker Sandbox** | `ct_cloud_read`와 `ct_cloud_write`                  | 워크스페이스 연결 자격 증명. 실행마다 주입되며 내 컴퓨터로는 절대 전송되지 않음 |

연결은 Sandbox가 쓸 수 있는 자격 증명이지, 세 번째 환경이 아닙니다. 에이전트는 채팅에서 Anna가 보는 것과 같은 연결 정보를 매 턴 갱신해 참조하므로, 브라우저에서 추가한 연결을 다음 프롬프트부터 쓸 수 있습니다.

하나의 명령에서 이름이 지정된 여러 AWS와 GCP 연결을 GitLab과 함께 쓸 수 있습니다. 어떤 별칭을 쓸지 에이전트에게 알려주세요. 클라우드 실행마다 자격 증명과 로컬 파일 변경은 분리되며, 새로 선언된 출력 파일만 워크스페이스로 돌아오고 기존 파일은 덮어쓰지 않습니다.

## 클라우드 도구

| 도구               | 용도                                                     | 실행 위치                              |
| ---------------- | ------------------------------------------------------ | ---------------------------------- |
| `ct_cloud_read`  | 버킷 나열이나 배포 조회처럼 범위가 한정된 읽기 전용 조사                       | CloudThinker Sandbox               |
| `ct_cloud_write` | 롤아웃 재시작처럼 이름을 댈 수 있는 상태 변경 명령 하나                       | 워크스페이스가 결정한 뒤 CloudThinker Sandbox |
| `ct_ask`         | 과거 인시던트 기억, 전문 에이전트, 서로 의존하는 여러 단계처럼 워크스페이스 자체가 필요한 작업 | Anna, 연결된 대화에서                     |

`ct_ask` 실행은 세션당 Anna 스레드를 하나 열고 재사용합니다. `ct_run_status`는 승인 후 일시 중지된 실행을 재개합니다.

## 클라우드 쓰기 승인하기

클라우드 쓰기는 호출이 아니라 워크스페이스가 결정하는 요청입니다. 에이전트가 요청하면 터미널이 편집기 위에 사유, 연결, 명령, 브라우저 링크가 담긴 카드를 고정해 보여줍니다.

| 결과 줄                                                                   | 의미                              |
| ---------------------------------------------------------------------- | ------------------------------- |
| `auto: allowed (trusted command) · ran in CloudThinker Sandbox · 2.0s` | Auto Mode가 허용해 즉시 실행됨           |
| `auto: needs approval`                                                 | Auto Mode가 사람의 판단을 기다리며 일시 중지함  |
| `manual: needs approval`                                               | 워크스페이스가 Manual이라 모든 쓰기가 멈춤      |
| `auto: escalated`                                                      | Auto Mode가 중단하고 경고를 올림. 실행되지 않음 |
| `auto: denied`                                                         | 정책이 차단함. 어떤 승인으로도 실행할 수 없음      |

카드에서 **Approve**, **Approve and trust this command**, **Decline** 중에 고릅니다. Escape를 누르면 거절입니다. [승인자](/ko/guide/approval)만 결정할 수 있고, 승인자인 팀원에게는 브라우저에도 같은 카드가 보입니다.

**Approve and trust this command**는 해당 명령을 워크스페이스 정책에 기록합니다. 채팅의 승인 대화 상자에 있는 Trust와 같은 것입니다. Auto에서는 그 명령이 다음부터 멈춤 없이 실행됩니다. Trust에는 워크스페이스 소유자 또는 관리자 권한이 필요합니다.

승인은 쓰기가 요청된 시점에 선택된 연결을 그대로 유지합니다. 연결을 추가해도 대기 중인 쓰기의 범위는 넓어지지 않으며, 접근 권한을 제거하거나 선택된 ID를 바꾸면 실행이 차단됩니다. 쓰기 결과가 불명으로 보고되면 다시 요청하기 전에 영향부터 확인하세요. 요청을 재개해도 명령이 자동으로 다시 실행되지는 않습니다.

## 터미널에서의 Auto Mode

Auto Mode는 워크스페이스의 단일 설정이며, 터미널은 자체 모드를 갖지 않고 그것을 보여줄 뿐입니다. `/cloudthinker auto`로 현재 모드를 출력합니다. `/cloudthinker auto on` 또는 `/cloudthinker auto off`로 워크스페이스 전체를 전환하며, 워크스페이스 설정 편집 권한이 필요하고 채팅에서의 전환과 동일하게 기록됩니다.

세션별 재정의는 없고, 노트북에서 승인을 우회하는 플래그도 없습니다. 내 컴퓨터의 로컬 명령은 CloudThinker의 게이트를 거치지 않고 pi가 사용자 권한으로 실행합니다.

## 알림

Agent CLI 세션은 스스로 승인 알림을 보내지 않습니다. 카드가 이미 터미널과 브라우저에 보이기 때문입니다. 세션의 `ct_ask` 스레드에서 Anna가 올리는 승인도 마찬가지입니다.

승인자가 아니라면 `/cloudthinker notify`를 실행해 [알림](/ko/guide/notifications)에서 설정한 채널로 승인 요청을 한 번 보낼 수 있습니다.

## 명령

| 명령                             | 동작                                    |
| ------------------------------ | ------------------------------------- |
| `/cloudthinker about`          | 버전, pi 출처 표기, 설정 디렉터리, 세션 링크          |
| `/cloudthinker session`        | 이 세션의 파일 수, 메시지 수, 토큰 수, 마지막에 청구된 크레딧 |
| `/cloudthinker auto [on\|off]` | 워크스페이스 승인 모드 출력 또는 전환                 |
| `/cloudthinker notify`         | 대기 중인 승인 요청을 워크스페이스 승인자에게 한 번 전송      |
| `/open`                        | 이 세션을 브라우저에서 열기                       |
| `/cloud`                       | 워크스페이스, 연결, 미러 상태 표시                  |

`/model`, `/fork`, `/settings` 같은 pi 자체 명령도 그대로 동작합니다. `/share`와 `/thinking`은 제거되었습니다.

## 세션 미러

모든 세션은 **Agent CLI** 대화로 워크스페이스에 미러링됩니다. 브라우저에서 열면 저장소, 브랜치, 도구 호출, 연결된 Anna 스레드를 담은 읽기 전용 뷰어가 보입니다. 세션을 소유한 터미널만 기록하므로 아무도 입력할 수 없습니다. 보기 권한이 있는 워크스페이스 구성원은 읽을 수 있고, 삭제는 워크스페이스 소유자만 할 수 있습니다.

기록은 pi의 세션 파일로 내 컴퓨터에 남습니다. 그 파일을 재개하면 같은 대화가 이어지고, `/fork`는 부모를 기록한 새 대화를 엽니다.

## 크레딧

푸터는 이 세션에 청구된 크레딧을 보여줍니다. 예: `◆ 1.75 credits`. 에이전트는 모델 가격을 통화로 표시하지 않습니다. 푸터에 미러 상태가 추가되는 것은 `✕ mirror offline, 3 pending`처럼 조치가 필요할 때뿐입니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal" href="/ko/guide/cli/overview">
    CloudThinker CLI 설치하고 로그인하기
  </Card>

  <Card title="Auto Mode" icon="bolt" href="/ko/guide/auto-mode">
    워크스페이스의 Manual 또는 Auto 선택
  </Card>

  <Card title="승인" icon="shield-check" href="/ko/guide/approval">
    승인자와 도구 권한
  </Card>

  <Card title="연결" icon="plug" href="/ko/guide/connections/overview">
    Sandbox가 사용할 연결 설정하기
  </Card>
</CardGroup>