Name: Keboola Agent CLI (kbagent)
SKU: -

소개

kbagent는 Keboola의 모든 프로젝트를 관리하기 위한 커맨드라인 인터페이스(CLI)입니다. AI 에이전트(Claude Code, Codex, Gemini, Cursor 등)의 구동을 염두에 두고 설계되었지만, 독립적으로 사용하기에도 적합합니다. UI, 기존 CLI, 원시 API 호출 간의 전환 없이 모든 작업을 워크플로우 중심의 명령어로 처리하며, 개발 브랜치 자동 전파, 병렬 다중 프로젝트 작업, 안전한 AI 에이전트 샌드박싱 등을 지원합니다.

상세정보

프로그램 소개

kbagent는 Keboola 데이터 플랫폼의 모든 프로젝트를 하나의 CLI로 통합 관리하는 강력한 도구입니다. AI 에이전트의 구동을 지원하도록 설계되어, 대규모 자동화 워크플로우와 솔로 사용 모두에 적합합니다.

주요 기능

다중 프로젝트 관리: 모든 연결된 프로젝트에 대해 명령어 하나로 병렬 쿼리 및 작업을 수행합니다.
크로스 프로젝트 검색: kbagent search 명령어로 모든 프로젝트의 테이블, 설정, 플로우, 데이터 앱을 한 번에 검색합니다.
설정 관리: 설정 목록 조회, 검색, 수정, 생성, 삭제와 함께 행 단위 CRUD, OAuth URL 생성, 변수 관리 등을 제공합니다.
스토리지 작업: 버킷, 테이블, 파일에 대한 전체 CRUD를 지원하며, CSV 자동 업로드, 파일 다운로드, Parquet 내보내기 등을 수행합니다.
개발 브랜치: 브랜치를 생성하고 활성화하면 모든 명령어가 해당 브랜치를 자동으로 대상으로 삼습니다.
GitOps 및 동기화: 설정을 YAML로 추출하여 IDE에서 편집하고 다시 푸시할 수 있으며, SQL/Python 파일을 실제 파일로 추출합니다.
에이전트 태스크: kbagent serve 내부에서 AI 에이전트를 CRON, 수동, 체이닝 방식으로 스케줄링하고 비용/토큰 타임라인을 추적합니다.
워크스페이스: Snowflake/BigQuery 워크스페이스를 생성하고 테이블을 로드하여 SQL을 직접 실행할 수 있습니다.
데이터 앱: Streamlit, Flask, Node 배포의 전체 생명주기를 관리하고, 비밀번호 관리, 배포 로그 조회 등을 지원합니다.

다운로드·설치 방법

Windows 환경에서는 여러 가지 방법으로 설치할 수 있습니다. 가장 간단한 방법은 PowerShell을 사용하는 것입니다.

PowerShell을 통한 설치 (권장):
다음 명령어를 PowerShell에서 실행하여 uv 패키지 관리자를 설치하고, 최신 버전의 kbagent를 설치합니다.
winget install –id astral-sh.uv -e
$ver = (Invoke-RestMethod “https://api.github.com/repos/keboola/cli/releases/latest”).tag_name.TrimStart(‘v’)
uv tool install –force “keboola-cli[server] @ https://github.com/keboola/cli/releases/download/v$ver/keboola_cli-$ver-py3-none-any.whl”
uv tool update-shell
설치 후 새 쉘을 열어 PATH 변경 사항을 적용해야 합니다.
Git for Windows 사용:
이미 Git for Windows가 설치되어 있다면, 해당 bash를 통해 공식 설치 스크립트를 실행할 수 있습니다.
& “C:Program FilesGitbinbash.exe” -lc “curl -LsSf https://raw.githubusercontent.com/keboola/cli/main/install.sh | sh”
바이너리 패키지 사용:
Python이나 uv 없이도 사용할 수 있습니다. GitHub 릴리스 페이지에서 ‘keboola-cli2_<version>_windows_amd64.zip’ 파일을 다운로드하여 압축을 풀고, 해당 폴더를 PATH에 추가하면 됩니다.

기본 사용법

설치 후 프로젝트를 연결하고 기본적인 명령어를 실행할 수 있습니다.

프로젝트 연결:
kbagent project add –project prod –url https://connection.keboola.com –token YOUR_TOKEN
전역 검색:
kbagent search “customer_id”
작업 실행:
kbagent job run –project prod –component-id keboola.ex-db-snowflake –config-id 456 –wait –log-tail-lines 200
설정 검색:
kbagent config search –query “customer_id”

이런 경우에 유용합니다

Keboola 플랫폼의 대규모 관리: 여러 프로젝트에 걸쳐 설정, 작업, 스토리지를 한 주소에서 통합 관리해야 할 때 유용합니다.
AI 에이전트 기반 자동화: Claude Code, Codex, Gemini 등과 연계하여 데이터 파이프라인 모니터링, 정리 조언, SQL 디버깅 등을 자동화할 때 적합합니다.
개발 및 테스트 환경 구성: 개발 브랜치를 사용하여 프로덕션 데이터를 건드리지 않고 안전하게 테스트하고, 브랜치 간 변경 사항을 비교할 수 있습니다.
데이터 앱 배포 및 관리: Streamlit이나 Flask로 만든 데이터 앱을 Keboola 위에 배포하고, 로그를 모니터링하며 비밀번호를 관리해야 할 때 사용합니다.

지원 환경·시스템 요구사항

운영 체제: Windows 10 1803 이상
Python: 3.12 이상 (uv가 자동으로 가져오거나, 환경 변수로 지정 가능)
기타 의존성: curl (설치 스크립트용), uv 패키지 관리자 (권장)

제한 사항·확인 사항

Chocolatey 패키지 지연: Chocolatey 패키지(keboola-cli2)는 현재 최신 버전보다 뒤처질 수 있으므로, 설치 전 버전을 확인하거나 다른 설치 방법을 사용하는 것이 좋습니다.
Windows 환경의 셸 제약: 기본적인 curl … | sh 설치 방법은 POSIX 셸이 필요하며, Windows의 cmd나 PowerShell에서는 작동하지 않습니다. PowerShell 스크립트 또는 Git for Windows의 bash를 사용해야 합니다.
Python 스텁 문제: 깨끗한 Windows 설치에는 실제 Python이 없을 수 있으며, python 명령어는 Microsoft Store 스텁을 가리킬 수 있습니다. kbagent 설치 방법은 PATH에 python이 없어도 정상 작동합니다.
윈게트 패키지 부재: 현재 WinGet 패키지는 제출되지 않았습니다.

FAQ

Q: kbagent는 무료인가요?
A: kbagent 자체는 Apache 2.0 라이선스로 배포되는 오픈소스 소프트웨어입니다. Keboola 플랫폼 사용에는 해당 플랫폼의 요금이 적용될 수 있습니다.
Q: Windows에서 설치할 때 Python이 반드시 필요한가요?
A: GitHub 릴리스 페이지에서 제공하는 자체 인터프리터를 포함하는 바이너리 패키지를 다운로드하면 Python이나 uv 없이도 사용할 수 있습니다.
Q: 인터넷 연결이 없어도 사용할 수 있나요?
A: 프로젝트 관리 및 설정 검색 등 로컬 캐시된 데이터를 기반으로 하는 일부 기능은 오프라인에서 작동할 수 있으나, Keboola 플랫폼과의 동기화나 API 호출이 필요한 기능은 인터넷 연결이 필요합니다.
Q: AI 에이전트를 사용하려면 별도의 설정이 필요한가요?
A: Claude Code 플러그인을 설치하고 kbagent:setup 명령어를 실행하면 자동으로 CLI 설치, 프로젝트 연결, 환경 검증이 수행됩니다. 다른 에이전트의 경우 kbagent context 명령어로 전체 명령어 참조를 제공할 수 있습니다.

시스템 요구사항

Python 3.12 이상이 필요합니다. 설치 시 uv 패키지 관리자가 자동으로 필요한 인터프리터를 가져오지만, 오프라인이거나 Python 다운로드가 비활성화된 경우 환경 변수 UV_PYTHON을 3.12 이상으로 설정해야 합니다.

Keboola Agent CLI (kbagent)

소개