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

# CLI tools

> Happycapy 샌드박스에서 명령줄 도구를 실행합니다.

## 개요

Command-line interface, 즉 CLI는 버튼 대신 명령으로 실행하는 도구입니다. 많은 서비스는 CLI를 제공해 사용자가 repository, 문서, 배포, 로그, workspace 데이터를 프로그래밍 방식으로 관리할 수 있게 합니다.

Happycapy에서는 이런 명령을 외울 필요가 없습니다. 원하는 일을 자연어로 설명하면 Happycapy가 CLI를 설치하고, 알맞은 명령을 고르고, 샌드박스에서 실행하고, 출력 결과를 읽은 뒤 같은 Project 안에서 작업을 이어갈 수 있습니다.

CLI는 GitHub, Notion, Lark, Fly.io 같은 외부 서비스에 연결할 수도 있고, 샌드박스 안에서 파일, 코드, 미디어, 데이터를 처리하는 로컬 유틸리티일 수도 있습니다.

## CLI tools를 사용할 때

서비스가 유용한 작업을 명령으로 제공한다면 CLI tools가 적합합니다.

* Repository, Pull Request, Issue, 로그, 배포 작업
* Notion, Lark 같은 workspace 시스템 읽기 또는 업데이트
* 클라우드, 데이터베이스, 인프라 명령 실행
* 반복 가능한 명령줄 작업을 Project workflow로 전환

## CLI와 MCP 구분하기

Happycapy에서 CLI와 MCP는 사용감이 꽤 비슷할 수 있습니다. 사용자는 자연어로 목표를 설명하고, agent가 필요한 tool call이나 명령을 판단합니다.

차이는 주로 연결 방식에 있습니다. CLI tools에서는 Happycapy가 샌드박스 안에서 명령줄 프로그램을 작성하고 실행합니다. [MCP](/ko/integrations/mcp)에서는 Happycapy가 MCP server가 노출한 도구를 호출합니다.

서비스에 잘 유지보수되는 공식 CLI가 있거나 배포, 로그, 스크립트, 파일 처리, 일회성 설정이 중심이라면 CLI가 더 직접적입니다. 잘 유지보수되는 MCP server가 있거나 도구 동작을 구조화된 인터페이스로 agent에게 노출하고 싶다면 MCP가 더 맞을 수 있습니다. 둘 다 있다면 공식적으로 유지보수되고, 권한이 명확하며, 설정이 가장 쉬운 쪽을 선택하세요.

## 시작하기 전에

다음 정보를 제공하면 좋습니다.

* 공식 CLI 이름 또는 설치 링크
* 연결할 account, workspace, repository 또는 app
* 필요한 인증 방식. login flow, token, API key, workspace permission 등
* 설정 후 Happycapy가 완료해야 하는 결과

## 첫 사용

Happycapy에 도구와 목표를 함께 알려주세요.

```text theme={null}
Happycapy 샌드박스에 [CLI name]을 설치해줘.
계속하기 전에 어떤 인증이 필요한지 알려줘.
준비가 끝나면 이것으로 [goal]을 완료해줘.

CLI 링크: [official link]
```

## 추천 CLI

이 CLI들은 Happycapy 샌드박스에서 사용하기 좋습니다. 실제 업무 시스템을 명령으로 제공하므로 agent가 설치, 설정, 실행을 도와줄 수 있습니다.

<CardGroup cols={2}>
  <Card title="GitHub CLI" icon="https://mintcdn.com/happycapy/9SccTkPwiYpehlgU/images/integrations/logos/github.png?fit=max&auto=format&n=9SccTkPwiYpehlgU&q=85&s=679bb093797d36e654af372f853a460a" href="https://cli.github.com" width="560" height="560" data-path="images/integrations/logos/github.png">
    Repository, Pull Request, Issue, GitHub Actions를 다룹니다.
  </Card>

  <Card title="ntn" icon="https://mintcdn.com/happycapy/9SccTkPwiYpehlgU/images/integrations/logos/notion.png?fit=max&auto=format&n=9SccTkPwiYpehlgU&q=85&s=534c589e6711180fe51fa3b632720e51" href="https://developers.notion.com/cli" width="64" height="64" data-path="images/integrations/logos/notion.png">
    Notion 페이지 검색, 콘텐츠 생성, 데이터베이스 조회에 사용합니다.
  </Card>

  <Card title="lark-cli" icon="https://mintcdn.com/happycapy/9SccTkPwiYpehlgU/images/integrations/logos/lark.png?fit=max&auto=format&n=9SccTkPwiYpehlgU&q=85&s=adc21fbe2f882fafdd5006135fb05128" href="https://github.com/larksuite/cli" width="48" height="48" data-path="images/integrations/logos/lark.png">
    Lark/Feishu 메시지, 문서, 시트, 캘린더, 작업, 메일, 회의를 다룹니다.
  </Card>

  <Card title="flyctl" icon="https://mintcdn.com/happycapy/9SccTkPwiYpehlgU/images/integrations/logos/flyio.svg?fit=max&auto=format&n=9SccTkPwiYpehlgU&q=85&s=d9342a993c06f2170919e5f5a526a3d3" href="https://fly.io/docs/flyctl/" width="167" height="151" data-path="images/integrations/logos/flyio.svg">
    Fly.io apps, Machines, 로그, secrets, releases를 배포하고 운영합니다.
  </Card>
</CardGroup>

## 워크플로 예시

```text theme={null}
GitHub CLI를 사용해줘.
이 repository의 가장 최근 실패한 GitHub Actions run을 확인해줘.
실패 원인을 요약하고 가장 작은 수정안을 제안해줘.
```

```text theme={null}
ntn을 사용해줘.
우리 Notion workspace에서 onboarding docs를 찾아줘.
현재 프로세스를 요약하고 부족한 부분을 목록으로 정리해줘.
```

```text theme={null}
lark-cli를 사용해줘.
Lark docs에서 이번 주 프로젝트 업데이트를 모아줘.
짧은 팀 보고서로 정리해줘.
```

```text theme={null}
flyctl을 사용해줘.
이 Fly.io app의 상태와 최근 로그를 확인해줘.
최신 deploy가 정상인지 알려줘.
```

## 인증과 권한

* CLI가 연결할 account, workspace, repository 또는 project부터 알려주세요.
* 가능하면 secrets를 prompt에 쓰지 마세요. CLI의 일반 인증 흐름을 우선 사용하세요.
* 인증을 승인하기 전에 Happycapy에게 필요한 권한을 설명하게 할 수 있습니다.
* token을 사용할 때 서비스가 지원한다면 scoped token 또는 short-lived token을 우선 사용하세요.
* 파괴적인 작업은 실행 전에 Happycapy에게 명령과 예상 영향을 보여달라고 요청하세요.

## 문제 해결

### CLI를 설치할 수 없음

공식 설치 링크를 공유하고 Happycapy에게 샌드박스 환경, package manager, platform requirements를 확인하게 하세요.

### Login failed

CLI가 browser login, token login, workspace approval, environment variables 중 무엇을 요구하는지 확인하세요.

### Permission denied

어떤 권한이 부족한지, 다른 token, role, workspace, repository, organization이 필요한지 Happycapy에게 확인하게 하세요.

### 출력이 너무 넓음

repository, project, date range, file path, app name, command target으로 요청 범위를 좁히세요.

## 다음 단계

* 다른 통합 방식을 알고 싶다면 [MCP](/ko/integrations/mcp)를 확인하세요. MCP는 CLI와 사용감이 비슷하지만, 샌드박스에서 명령줄 프로그램을 실행하는 대신 MCP server의 도구를 호출합니다.
* 같은 CLI workflow를 일정에 따라 실행하려면 [Automations](/ko/features/automations)를 사용하세요.