Lark/Feishu CLI: 인간과 AI 에이전트 모두를 위해 설계된 Lark/Feishu의 공식 커맨드라인 도구

9bow · 4월 5, 2026, 9:30오전

Lark/Feishu CLI 소개

Lark(중국 서비스명 Feishu)는 바이트댄스(ByteDance)에서 개발한 강력한 엔터프라이즈 협업 플랫폼으로, 메시징, 문서, 캘린더, 화상 회의 등 다양한 업무 기능을 단일 시스템으로 통합하여 제공합니다. 전 세계의 수많은 기업들이 조직의 생산성과 소통 효율성을 높이기 위해 Lark를 전사적으로 도입하고 있으며, 이에 따라 플랫폼 기반의 개발자 생태계 또한 지속적으로 확장되고 있습니다. 이러한 업무 환경 속에서 소프트웨어 엔지니어들은 웹 브라우저나 데스크톱 앱 인터페이스를 넘어, 터미널 환경에서 즉각적으로 Lark의 방대한 기능을 제어하고 업무를 자동화할 필요성을 느끼게 되었습니다.

과거에는 시스템을 자동화하기 위해 공식 오픈 플랫폼의 REST API를 직접 호출해야 했고, 이 과정에서 복잡한 OAuth 인증 처리와 까다로운 페이로드 구성 등 번거로운 작업이 수반되었습니다. 하지만 이번에 공식적으로 공개된 커맨드라인 인터페이스(CLI) 도구는 이러한 개발자들의 고충을 정확하게 해결하며, 훨씬 빠르고 매끄러운 개발자 경험(DX)을 선사합니다.

Lark/Feishu CLI(일명 lark-cli)는 Larksuite 공식 팀에서 직접 개발하고 유지보수하는 오픈소스 기반의 커맨드라인 도구입니다. 이 프로젝트의 가장 핵심적인 철학은 단순한 터미널 관리 도구에 머무는 것이 아니라, 사람(개발자)과 AI 에이전트 모두가 직관적이고 효율적으로 사용할 수 있도록 근본부터 설계되었다는 점입니다.

현재 이 CLI 도구는 메신저, 문서(Docs), 베이스(Base), 스프레드시트, 캘린더, 이메일, 할 일(Tasks), 회의 등 Lark의 핵심 비즈니스 도메인을 모두 포괄하는 강력한 커버리지를 자랑합니다. 무려 200개 이상의 정교하게 선별된 명령어와 20여 개의 AI 에이전트 스킬(Agent Skills)을 기본으로 내장하여 광범위한 업무 자동화를 지원합니다. 게다가 앱 생성부터 대화형 로그인, 첫 API 호출까지의 과정을 단 3분 만에 완료할 수 있도록 구성되어 있어, 도구 도입에 대한 진입 장벽을 혁신적으로 낮췄습니다.

특히 최근 IT 업계에서 AI 에이전트의 활용도가 폭발적으로 증가함에 따라, LLM(대형 언어 모델)이 외부 애플리케이션과 상호작용할 수 있도록 돕는 안정적인 도구의 가치가 급상승하고 있습니다. Lark CLI는 이러한 트렌드를 반영하여 철저하게 '에이전트 네이티브(Agent-Native)' 디자인을 채택했습니다. 널리 쓰이는 최신 AI 도구들과 원활하게 호환되는 구조화된 스킬셋을 제공하므로, 개발자는 복잡한 통합 과정 없이도 AI 에이전트에게 Lark 시스템 조작 권한을 부여할 수 있습니다.

또한, 에이전트의 API 호출 성공률을 극대화하기 위해 모든 명령어를 실제 에이전트 환경에서 테스트하였으며, 간결한 파라미터 구조, 스마트한 기본값 할당, 명확히 구조화된 결과 출력 등의 최적화 작업을 거쳤습니다. 이를 통해 엔지니어들은 AI 기반의 차세대 업무 자동화 파이프라인을 더욱 견고하고 손쉽게 구축할 수 있게 되었습니다.

Lark/Feishu CLI의 주요 기능

광범위한 비즈니스 도메인 지원

Lark CLI는 일상적인 업무에 필요한 거의 모든 Lark 서비스에 접근할 수 있습니다:

카테고리	기능
캘린더	일정 확인, 이벤트 생성, 참석자 초대, 참석 가능/바쁨 상태 확인, 시간 제안
메신저	메시지 전송/답장, 그룹 채팅 생성 및 관리, 채팅 기록 및 스레드 보기, 메시지 검색, 미디어 다운로드
문서	문서 생성, 읽기, 업데이트 및 검색, 미디어 및 화이트보드 읽기/쓰기
드라이브	파일 업로드 및 다운로드, 문서 및 위키 검색, 댓글 관리
베이스	테이블, 필드, 레코드, 뷰, 대시보드, 워크플로, 양식, 역할 및 권한, 데이터 집계 및 분석 생성 및 관리
시트	스프레드시트 데이터 생성, 읽기, 쓰기, 추가, 찾기 및 내보내기
작업	작업 생성, 조회, 업데이트 및 완료; 작업 목록, 하위 작업, 댓글 및 알림 관리
위키	지식 공간, 노드 및 문서 생성 및 관리
연락처	이름/이메일/전화번호로 사용자 검색, 사용자 프로필 확인
메일	이메일 탐색, 검색, 읽기, 전송, 답장, 전달, 임시보관함 관리, 새 메일 확인
회의	회의 기록 검색, 회의록 및 녹화본 조회
결재	결재 작업 조회, 작업 승인/반려/전달, 진행 건 취소 및 참조(CC)

안전하고 통제 가능한 보안 환경

명령어 기반의 툴인 만큼 보안과 권한 통제에도 많은 신경을 썼습니다. 입력 인젝션(Input injection) 방어 기능을 비롯해 터미널 출력 데이터의 무결성 검증, 운영체제(OS) 네이티브의 안전한 키체인(Keychain) 기반 자격 증명 저장 기능을 기본적으로 탑재하고 있습니다. 이를 통해 민감한 기업 데이터에 접근할 때 발생할 수 있는 보안 취약점을 원천적으로 차단합니다.

3계층 커맨드 시스템 (Three-Layer Architecture)

Lark CLI는 사용자의 목적과 요구되는 정밀도에 따라 유연하게 선택할 수 있는 세 가지 수준의 명령어 아키텍처를 제공합니다:

숏컷 (Shortcuts): 명령어 앞에 + 기호가 붙는 형태로, 인간과 AI 에이전트 모두에게 가장 친화적인 방식입니다. 스마트 기본값, 깔끔한 테이블 형태의 출력, 변경 사항을 미리 확인할 수 있는 드라이 런(dry-run) 기능을 제공합니다.
```
# 캘린더 일정 확인
lark-cli calendar +agenda

# 특정 채팅방에 메시지 전송
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"

# 주간 보고서 문서 생성
lark-cli docs +create --title "Weekly Report" --markdown "# Progress\n- Completed feature X"
```
API 커맨드 (API Commands): Lark OAPI 메타데이터로부터 자동 생성되어 철저한 품질 검증을 거친 명령어입니다. 플랫폼 엔드포인트와 1:1로 매핑되는 100개 이상의 명령어를 통해 보다 구체적이고 세밀한 조작이 가능합니다.
```
# 캘린더 리스트 조회
lark-cli calendar calendars list

# 특정 캘린더의 기간별 이벤트 조회 (파라미터 전달)
lark-cli calendar events instance_view --params    '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'
```

Raw API 호출: 공식 문서에 명시된 2,500개 이상의 Lark Open Platform 엔드포인트를 직접 호출할 수 있는 로우 레벨 환경입니다. 숏컷이나 API 커맨드에서 제공하지 않는 세부 기능을 사용할 때 유용합니다.

# API 직접 GET 요청
lark-cli api GET /open-apis/calendar/v4/calendars

# API 직접 POST 요청 및 본문(body) 포함
lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_id"}' --body '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'

Lark/Feishu CLI 설치 및 사용법

Lark/Feishu CLI를 설치하고 사용하려면 기본적으로 Node.js 환경(npm 또는 npx)이 필요합니다. 만약 소스 코드에서 직접 빌드하고자 한다면 Go v1.23 이상 및 Python 3가 추가로 요구됩니다.

패키지 설치

일반 사용자와 AI 에이전트 모두 npm을 활용하여 간편하게 설치할 수 있습니다. AI 에이전트용 스킬 패키지를 추가로 전역 설치하는 것이 권장됩니다.

# CLI 기본 패키지 설치
npm install -g @larksuite/cli

# CLI 스킬 패키지 설치 (권장)
npx skills add larksuite/cli -y -g

권한 설정 및 로그인 (일반 사용자)

설치 후 대화형 안내에 따라 앱 자격 증명을 설정하고 계정에 로그인할 수 있습니다. --recommend 플래그를 사용하면 자주 사용되는 권한 범위(Scope)를 자동으로 선택하여 승인 절차를 간소화합니다.

# 1. 앱 자격 증명 초기화 및 설정
lark-cli config init

# 2. 브라우저를 통한 권한 로그인
lark-cli auth login --recommend

# 3. CLI 기능 사용 시작
lark-cli calendar +agenda

AI 에이전트를 위한 팁: 에이전트 환경에서는 lark-cli config init --new 및 lark-cli auth login --recommend 명령어를 백그라운드에서 실행하고, 결과로 출력되는 인가(Authorization) URL을 추출하여 사용자에게 브라우저를 통해 인증을 완료하도록 유도할 수 있습니다.

고급 기능 활용

출력 포맷 지원: 터미널 환경 및 다른 파이프라인과의 연동을 위해 다양한 포맷을 지원합니다. 기본적으로 전체 JSON 형식(--format json)을 사용하며, 가독성 높은 출력(--format pretty), 표 형식(--format table), 파이프 처리를 위한 줄바꿈 JSON(--format ndjson), 그리고 CSV(--format csv) 중에서 선택할 수 있습니다.
페이지네이션 제어: 대량의 데이터를 다룰 때 --page-all을 통해 모든 페이지를 자동으로 넘기거나, --page-limit 5와 같이 제한을 둘 수 있습니다. API 과부하를 막기 위해 --page-delay 500과 같이 요청 간 딜레이를 설정하는 것도 가능합니다.
드라이 런(Dry Run): 데이터를 생성, 수정, 삭제하는 등의 사이드 이펙트가 발생할 수 있는 명령어의 경우, --dry-run 플래그를 추가하여 실제 실행 전에 어떤 요청이 전송될지 미리 안전하게 확인할 수 있습니다.
계정/봇 신원 전환: --as user 또는 --as bot 플래그를 사용하여 특정 명령을 실행할 주체를 유연하게 변경할 수 있습니다.

라이선스

Lark/Feishu CLI 프로젝트는 MIT 라이선스로 공개 및 배포 되고 있습니다.

Lark 공식 홈페이지

Lark/Feishu CLI 프로젝트 GitHub 저장소

Lark Open Platform 개발자 문서

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~