cli

KO | EN

gitlite — search

#ai-agents #llm #python #claude-code #typescript #mcp #ai #developer-tools #anthropic #claude #cli #rust

★ 16,485 Open GitHub ↗

larksuite 팀에서 공식적으로 유지보수하는 Lark/飞书 CLI 도구로, 사람과 AI Agent를 위해 제작되었습니다. Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings 등을 포함한 핵심 비즈니스 도메인을 다루며, 200개 이상의 명령어와 20개 이상의 AI Agent Skills를 제공합니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# lark-cli
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
[![npm version](https://img.shields.io/npm/v/@larksuite/cli.svg)](https://www.npmjs.com/package/@larksuite/cli)
[中文版](./README.zh.md) | [English](./README.md)
[larksuite](https://github.com/larksuite) 팀이 유지 관리하는 공식 [Lark/Feishu](https://www.larksuite.com/) CLI 도구로, 인간과 AI Agent를 위해 제작되었습니다. Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown 등을 포함한 핵심 비즈니스 도메인을 아우르며, 200개 이상의 커맨드와 26개의 AI Agent [Skills](./skills/)를 제공합니다.
[설치](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [인증](#authentication) · [커맨드](#three-layer-command-system) · [고급 사용법](#advanced-usage) · [보안](#security--risk-warnings-read-before-use) · [기여하기](#contributing)
## 왜 lark-cli인가요?
- \*\*Agent-Native 설계\*\* — 기본 제공되는 24개의 구조화된 [Skills](./skills/)로 인기 AI 도구와 호환되며, 추가 설정 없이 Agent가 Lark를 조작할 수 있습니다.
- \*\*광범위한 커버리지\*\* — 18개의 비즈니스 도메인, 200개 이상의 엄선된 커맨드, 26개의 AI Agent [Skills](./skills/)
- \*\*AI 친화적 및 최적화\*\* — 모든 커맨드는 실제 Agent로 테스트되었으며, 간결한 파라미터, 스마트 기본값, 구조화된 출력을 통해 Agent 호출 성공률을 극대화합니다.
- \*\*오픈 소스, 진입 장벽 제로\*\* — MIT 라이선스, 바로 사용 가능, 간단히 `npm install` 실행
- \*\*3분 만에 시작하기\*\* — 원클릭 앱 생성, 대화형 로그인, 설치부터 첫 API 호출까지 단 3단계
- \*\*안전하고 제어 가능\*\* — 입력 인젝션 방지, 터미널 출력 살균(sanitization), OS 기본 키체인 자격 증명 저장
- \*\*3계층 아키텍처\*\* — Shortcuts(사람 및 AI 친화적) → API Commands(플랫폼 동기화) → Raw API(전체 커버리지) 중에서 적절한 세분화 단계를 선택하세요.
## 주요 기능
| 카테고리 | 기능 |
| ------------- |-----------------------------------------------------------------------------------------------------------------------------------|
| 📅 Calendar | 일정 보기, 생성 및 수정, 참석자 초대, 회의실 찾기, 초대 응답(RSVP), 바쁨/한가함 및 시간 제안 확인 |
| 💬 Messenger | 메시지 전송/답장, 그룹 채팅 생성 및 관리, 채팅 기록 및 스레드 보기, 메시지 검색, 미디어 다운로드 |
| 📄 Docs | 문서 생성, 읽기, 수정 및 검색, 미디어 및 화이트보드 읽기/쓰기 |
| 📁 Drive | 파일 업로드 및 다운로드, 문서 및 위키 검색, 댓글 관리 |
| 📝 Markdown | Drive 네이티브 `.md` 파일 생성, 가져오기, 패치 및 덮어쓰기 |
| 📊 Base | 테이블, 필드, 레코드, 뷰, 대시보드, 워크플로, 폼, 역할 및 권한, 데이터 집계 및 분석 생성 및 관리 |
| 📈 Sheets | 스프레드시트 데이터 생성, 읽기, 쓰기, 추가, 찾기 및 내보내기 |
| 🖼️ Slides | 프레젠테이션 생성 및 관리, 프레젠테이션 콘텐츠 읽기, 슬라이드 추가 또는 제거 |
| ✅ Tasks | 작업 생성, 조회, 수정 및 완료; 작업 목록, 하위 작업, 댓글 및 미리 알림 관리 |
| 📚 Wiki | 지식 스페이스, 노드 및 문서 생성 및 관리 |
| 👤 Contact | 이름/이메일/전화번호로 사용자 검색, 사용자 프로필 가져오기 |
| 📧 Mail | 이메일 탐색, 검색, 읽기, 전송, 답장, 전달, 초안 관리, 새 메일 감시 |
| 🎥 Meetings | 회의 기록 검색, 회의록 아티팩트 및 녹음 조회 |
| 🕐 Attendance | 개인 출근 기록 조회 |
| ✍️ Approval | 결재 작업 조회, 작업 승인/반려/이전, 인스턴스 취소 및 참조(CC) |
| 🎯 OKR | OKR 조회, 생성, 수정; 목표 및 핵심 결과, 정렬, 지표 및 진행 상황 관리 |
| 📋 Project | Meegle — 독립형 [meegle-cli](https://github.com/larksuite/meegle-cli)를 통해 작업 항목, 일정 및 데이터 관리 (별도 설치 필요) |
| 🔗 Apps | Spark/Miaoda 앱 생성, HTML/정적 사이트 배포, 클라우드 생성 실행 및 접근 범위 관리 |
## 설치 및 빠르게 시작하기
### 요구 사항
시작하기 전에 다음 사항이 준비되어 있는지 확인하세요.
- Node.js (`npm`/`npx`)
- Go `v1.23` 이상 및 Python 3 (소스에서 빌드하는 경우에만 필요)
### 빠르게 시작하기 (일반 사용자)
> \*\*AI 어시스턴트를 위한 참고 사항:\*\* 설치를 돕는 AI Agent인 경우, 완료해야 하는 모든 단계가 포함된 [Quick Start (AI Agent)](#quick-start-ai-agent)로 바로 이동하세요.
#### 설치
다음 방법 중 \*\*하나\*\*를 선택하세요:
\*\*방법 1 — npm에서 설치 (권장):\*\*
```bash
npx @larksuite/cli@latest install
```
\*\*방법 2 — 소스에서 빌드:\*\*
Go `v1.23` 이상 및 Python 3가 필요합니다.
```bash
git clone https://github.com/larksuite/cli.git
cd cli
make install
# CLI SKILL 설치 (필수)
npx skills add larksuite/cli -y -g
```
#### 설정 및 사용
```bash
# 1. 앱 자격 증명 설정 (최초 1회, 대화형 안내 설정)
lark-cli config init
# 2. 로그인 (--recommend는 자주 사용하는 권한 범위를 자동으로 선택합니다)
lark-cli auth login --recommend
# 3. 사용 시작하기
lark-cli calendar +agenda
```
## 빠르게 시작하기 (AI Agent)
> 다음 단계는 AI Agent를 위한 것입니다. 일부 단계는 사용자가 브라우저에서 작업을 완료해야 합니다.
\*\*1단계 — 설치\*\*
```bash
npx @larksuite/cli@latest install
```
\*\*2단계 — 앱 자격 증명 설정\*\*
> 이 커맨드를 백그라운드에서 실행하세요. 인증 URL이 출력됩니다. 이를 추출하여 사용자에게 전송하세요. 사용자가 브라우저에서 설정을 완료하면 커맨드가 자동으로 종료됩니다.
```bash
lark-cli config init --new
```
\*\*3단계 — 로그인\*\*
> 위와 동일: 백그라운드에서 실행하고 인증 URL을 추출하여 사용자에게 전송합니다.
```bash
lark-cli auth login --recommend
```
\*\*4단계 — 확인\*\*
```bash
lark-cli auth status
```
## Agent Skills
| Skill | 설명 |
| ------------------------------- |----------------------------------------------------------------------------------------------------------------|
| `lark-shared` | 앱 설정, 인증 로그인, 신원 전환, 권한 범위 관리, 보안 규칙 (모든 다른 skill에 의해 자동 로드됨) |
| `lark-calendar` | 캘린더 이벤트(생성/수정), 안건 보기, 바쁨/한가함 조회, 시간 제안, 회의실 찾기, RSVP 응답 |
| `lark-im` | 메시지 전송/답장, 그룹 채팅 관리, 메시지 검색, 이미지 및 파일 업로드/다운로드, 리액션 |
| `lark-doc` | 문서 생성, 읽기, 수정, 검색 (마크다운 기반) |
| `lark-drive` | 파일 업로드, 다운로드, 권한 및 댓글 관리 |
| `lark-markdown` | Drive 네이티브 마크다운 파일 생성, 가져오기, 패치 및 덮어쓰기 |
| `lark-sheets` | 스프레드시트 생성, 읽기, 쓰기, 추가, 찾기, 내보내기 |
| `lark-slides` | 프레젠테이션 생성 및 관리, 프레젠테이션 콘텐츠 읽기, 슬라이드 추가 또는 제거 |
| `lark-base` | 테이블, 필드, 레코드, 뷰, 대시보드, 데이터 집계 및 분석 |
| `lark-task` | 작업, 작업 목록, 하위 작업, 미리 알림, 담당자 지정 |
| `lark-mail` | 이메일 탐색, 검색, 읽기, 전송, 답장, 전달, 초안 관리, 새 메일 감시 |
| `lark-contact` | 이름/이메일/전화번호로 사용자 검색, 사용자 프로필 가져오기 |
| `lark-wiki` | 지식 스페이스, 노드, 문서 |
| `lark-event` | 실시간 이벤트 구독 (WebSocket), 정규식 라우팅 및 agent 친화적 형식 |
| `lark-vc` | 회의 기록 검색, 회의록 조회 (요약, 할 일, 대화록) |
| `lark-whiteboard` | 화이트보드/차트 DSL 렌더링 |
| `lark-minutes` | 회의록 메타데이터 및 AI 아티팩트 (요약, 할 일, 챕터); 오디오/비디오를 업로드하여 회의록 생성, 미디어 다운로드 |
| `lark-openapi-explorer` | 공식 문서에서 내부 API 탐색 |
| `lark-skill-maker` | 커스텀 skill 생성 프레임워크 |
| `lark-attendance` | 개인 출근 기록 조회 |
| `lark-approval` | 결재 작업 조회, 작업 승인/반려/이전, 인스턴스 취소 및 참조(CC) |
| `lark-workflow-meeting-summary` | 워크플로: 회의록 집계 및 구조화된 보고서 |
| `lark-workflow-standup-report` | 워크플로: 안건 및 할 일 요약 |
| `lark-okr` | OKR 조회, 생성, 수정; 목표 및 핵심 결과, 정렬 및 지표 관리 |
## 인증
| 커맨드 | 설명 |
| ------------- | -------------------------------------------------------------- |
| `auth login` | 대화형 선택 또는 권한 범위용 CLI 플래그를 사용한 OAuth 로그인 |
| `auth logout` | 로그아웃 및 저장된 자격 증명 제거 |
| `auth status` | 현재 로그인 상태 및 부여된 권한 범위 표시 |
| `auth check` | 특정 권한 범위 확인 (종료 코드 0 = 정상, 1 = 누락) |
| `auth scopes` | 앱에서 사용 가능한 모든 권한 범위 나열 |
| `auth list` | 인증된 모든 사용자 나열 |
```bash
# 대화형 로그인 (TUI가 도메인 및 권한 수준 선택 안내)
lark-cli auth login
# 도메인별 필터링
lark-cli auth login --domain calendar,task
# 권장 자동 승인 권한 범위
lark-cli auth login --recommend
# 정확한 권한 범위
lark-cli auth login --scope "calendar:calendar:read"
# Agent 모드: 검증 URL 즉시 반환, 논블로킹
lark-cli auth login --domain calendar --no-wait
# 나중에 폴링 재개
lark-cli auth login --device-code 
# 신원 전환: 사용자 또는 봇으로 커맨드 실행
lark-cli calendar +agenda --as user
lark-cli im +messages-send --as bot --chat-id "oc\_xxx" --text "Hello"
```
## 3계층 커맨드 시스템
이 CLI는 빠른 작업부터 완전한 커스텀 API 호출까지 아우르는 3가지 세분화 단계를 제공합니다.
### 1. Shortcuts
`+` 접두사가 붙으며, 사람과 AI 모두에게 친화적으로 설계되었고 스마트 기본값, 테이블 출력, dry-run 미리보기를 제공합니다.
```bash
lark-cli calendar +agenda
lark-cli im +messages-send --chat-id "oc\_xxx" --text "Hello"
lark-cli docs +create --doc-format markdown --content $'Weekly Report\n# Progress\n- Completed feature X'
```
모든 shortcut 커맨드를 보려면 `lark-cli --help`를 실행하세요.
### 2. API Commands
Lark OAPI 메타데이터에서 자동 생성되며, 평가 및 품질 관리를 거쳐 엄선되었습니다. 플랫폼 엔드포인트와 1:1로 매핑되는 100개 이상의 커맨드입니다.
```bash
lark-cli calendar calendars list
lark-cli calendar events instance\_view --params '{"calendar\_id":"primary","start\_time":"1700000000","end\_time":"1700086400"}'
```
### 3. Raw API Calls
2,500개 이상의 API를 아우르는 Lark Open Platform 엔드포인트를 직접 호출합니다.
```bash
lark-cli api GET /open-apis/calendar/v4/calendars
lark-cli api POST /open-apis/im/v1/messages --params '{"receive\_id\_type":"chat\_id"}' --data '{"receive\_id":"oc\_xxx","msg\_type":"text","content":"{\"text\":\"Hello\"}"}'
```
## 고급 사용법
### 출력 형식
```bash
--format json # 전체 JSON 응답 (기본값)
--format pretty # 사람이 읽기 편하게 포맷된 출력
--format table # 읽기 쉬운 테이블
--format ndjson # 줄 바꿈으로 구분된 JSON (파이핑용)
--format csv # 쉼표로 구분된 값
```
### JSON 출력 규약
`--format json`(기본값) 사용 시, 성공 및 오류 봉투(envelope)가 구분됩니다.
성공 시 \*\*stdout\*\*으로 출력되며, 종료 코드는 `0`입니다:
```json
{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
```
오류 시 \*\*stderr\*\*로 출력되며, 0이 아닌 종료 코드를 반환합니다:
```json
{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
```
커맨드 성공 여부를 확인할 때는 `code == 0`이 \*\*아니라\*\* `ok == true`(또는 종료 코드)를 테스트하세요. 원시 OpenAPI 응답(`{"code": 0, "msg": "ok", ...}`)과 달리, 성공 봉투에는 `code`나 `msg` 필드가 없으며, `code`는 업스트림 OpenAPI 코드로서 `error` 내부에만 나타납니다. 전체 오류 분류 체계는 [errs/ERROR\_CONTRACT.md](errs/ERROR\_CONTRACT.md)를 참조하세요.
### 페이지네이션
```bash
--page-all # 모든 페이지 자동 페이지네이션
--page-limit 5 # 최대 5페이지
--page-delay 500 # 페이지 요청 간 500ms 지연
```
### Dry Run
부작용이 있을 수 있는 커맨드의 경우, 먼저 `--dry-run`으로 요청을 미리 확인하세요.
```bash
lark-cli im +messages-send --chat-id oc\_xxx --text "hello" --dry-run
```
### 스키마 인트로스펙션
스키마를 사용하여 모든 API 메서드의 파라미터, 요청 본문, 응답 구조, 지원되는 신원 및 권한 범위를 검사할 수 있습니다.
```bash
lark-cli schema
lark-cli schema calendar.events.instance\_view
lark-cli schema im.messages.delete
```
## 보안 및 위험 경고 (사용 전 필독)
이 도구는 AI Agent가 호출하여 Lark/Feishu Open Platform에서 작업을 자동화할 수 있으며, 모델 할루시네이션, 예측 불가능한 실행, 프롬프트 인젝션 등 내재된 위험을 수반합니다. Lark/Feishu 권한을 승인하면 AI Agent는 승인된 범위 내에서 사용자 신원으로 행동하게 되며, 이는 민감 데이터 유출이나 무단 작업 등 고위험 결과로 이어질 수 있습니다. 주의해서 사용하세요.
이러한 위험을 줄이기 위해 이 도구는 여러 계층에서 기본 보안 보호 기능을 활성화합니다. 그러나 이러한 위험은 여전히 존재합니다. 어떠한 기본 보안 설정도 임의로 수정하지 않을 것을 강력히 권장합니다. 관련 제한이 완화되면 위험이 크게 증가하며, 그 결과는 사용자가 부담하게 됩니다.
이 도구와 통합된 Lark/Feishu 봇을 개인 대화형 어시스턴트로 사용하는 것을 권장합니다. 권한 남용이나 데이터 유출을 방지하기 위해 그룹 채팅에 추가하거나 다른 사용자가 상호작용하도록 허용하지 마세요.
액세스 토큰 도난과 관련된 보안 위험을 줄이기 위해, CLI는 공식 Feishu/Lark HTTPS 도메인으로 이루어지는 OpenAPI 요청 시 최소한의 위험 제어 신호를 전송합니다. 이 신호는 비정상적인 API 활동을 식별하는 데 사용됩니다. 이 보호 기능은 기본적으로 활성화되어 있습니다. 전송되는 정보는 다음으로 제한됩니다:
- 운영 체제 유형: macOS, Windows 또는 Linux
- 장치 하드웨어 모델: 예: Mac17,9
현재 워크스페이스에서 이 보호 기능을 비활성화하려면 다음을 실행하세요:
```bash
lark-cli config risk-control off
```
현재 워크스페이스에서 이 보호 기능을 활성화하려면 다음을 실행하세요:
```bash
lark-cli config risk-control on
```
현재 워크스페이스의 기본 정책을 복원하려면 다음을 실행하세요:
```bash
lark-cli config risk-control default
```
모든 사용 위험을 완전히 숙지하시기 바랍니다. 이 도구를 사용함으로써 관련된 모든 책임을 자발적으로 부담하는 것으로 간주됩니다.
## 기여하기
커뮤니티의 기여를 환영합니다! 버그를 발견하거나 기능 제안이 있는 경우 [Issue](https://github.com/larksuite/cli/issues) 또는 [Pull Request](https://github.com/larksuite/cli/pulls)를 제출해 주세요.
대규모 변경의 경우, 먼저 Issue를 통해 당사와 논의하는 것을 권장합니다.
PR을 열기 전에 기여자 및 AI agent가 사용하는 로컬 빌드, 테스트, PR 체크리스트에 대해 [AGENTS.md](./AGENTS.md)를 참조하세요.
## 라이선스
이 프로젝트는 \*\*MIT License\*\*에 따라 라이선스가 부여됩니다.
실행 시 Lark/Feishu Open Platform API를 호출합니다. 이러한 API를 사용하려면 다음 계약 및 개인정보 처리방침을 준수해야 합니다:
- [Feishu 사용자 서비스 약관](https://www.feishu.cn/terms)
- [Feishu 개인정보 처리방침](https://www.feishu.cn/privacy)
- [Feishu Open Platform 앱 서비스 제공업체 보안 관리 사양](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
- [Lark 사용자 서비스 약관](https://www.larksuite.com/user-terms-of-service)
- [Lark 개인정보 처리방침](https://www.larksuite.com/privacy-policy)

cli

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README