Butler Agent CLI

Butler Agent CLI는 데스크톱 앱 없이 Butler 런타임을 설치하고 실행하는 명령줄 도구입니다. standalone Agent 아카이브에 들어 있으며, 서비스 시작과 중지, 설치 점검, 모델과 설정 관리, MCP 서버 실행을 명령으로 처리합니다.

지원 환경

• Apple Silicon Mac(darwin-arm64) 전용입니다. Linux와 Intel Mac에서는 실행되지 않습니다.
• 네이티브 Agent 아카이브(butler-agent-<버전>-darwin-arm64.tar.gz)를 게시한 릴리스가 필요합니다.

설치

아카이브는 버전마다 새 폴더에 풀어 쓰는 설치 패키지입니다. 실행 중에 바뀌는 데이터는 설치 폴더가 아니라 데이터 폴더(기본값 ~/.butler)에 저장합니다.

set -euo pipefail
VERSION=0.0.21 # 네이티브 Agent 아카이브가 있는 릴리스 버전으로 바꿉니다.
ARCHIVE="butler-agent-${VERSION}-darwin-arm64.tar.gz"
RELEASE_URL="https://github.com/Hexpy-Games/butler/releases/download/v${VERSION}"
DOWNLOAD_DIR="$HOME/Downloads/butler-agent-${VERSION}"
INSTALL_ROOT="$HOME/.local/opt/butler-agent"
INSTALL_DIR="$INSTALL_ROOT/$VERSION"
export BUTLER_DATA="${BUTLER_DATA:-$HOME/.butler}"

mkdir -p "$DOWNLOAD_DIR" "$INSTALL_ROOT" "$BUTLER_DATA"
cd "$DOWNLOAD_DIR"
curl -fL --retry 3 -o "$ARCHIVE" "$RELEASE_URL/$ARCHIVE"
SUMS="butler-${VERSION}-SHA256SUMS"
curl -fL --retry 3 -o "$SUMS" "$RELEASE_URL/$SUMS"
EXPECTED_SHA256="$(awk -v name="$ARCHIVE" '$2 == name { print $1 }' "$SUMS")"
test "${#EXPECTED_SHA256}" -eq 64
printf '%s  %s\n' "$EXPECTED_SHA256" "$ARCHIVE" | shasum -a 256 -c -

if [ -e "$INSTALL_DIR" ]; then
  printf 'Installation already exists; choose a new version directory: %s\n' "$INSTALL_DIR" >&2
  exit 1
fi
mkdir "$INSTALL_DIR"
tar -xzf "$ARCHIVE" -C "$INSTALL_DIR"
"$INSTALL_DIR/butler" --data "$BUTLER_DATA" version --json
"$INSTALL_DIR/butler" --data "$BUTLER_DATA" doctor --check installation --json

설치 폴더에는 다음 파일이 들어 있습니다.

• butler-agent: 실행 파일입니다.
• butler: butler-agent를 가리키는 링크입니다. 이 문서의 명령은 butler로 적습니다.
• resources/: 실행에 필요한 리소스입니다.
• native-agent-manifest.json: 버전과 SHA-256 정보를 담은 설치 매니페스트입니다.

PATH에 추가하기 (선택)

전체 경로 없이 butler로 실행하려면 설치 폴더를 PATH에 추가합니다. 셸 설정 파일(~/.zshrc 등)에 넣으면 새 터미널에서도 적용됩니다.

export PATH="$HOME/.local/opt/butler-agent/0.0.21:$PATH"
butler version

기본 사용법

데이터 폴더 지정

Agent 명령은 데이터 폴더 하나를 대상으로 실행합니다. 다음 순서로 먼저 찾은 값을 씁니다.

1. --data PATH 옵션
2. BUTLER_DATA 환경 변수
3. ~/.butler

butler --data ~/butler-test status
BUTLER_DATA=~/butler-test butler status

도움말과 명령 목록

butler help
butler help mcp
butler commands --json

butler help <명령>은 해당 명령 아래의 하위 명령만 보여 줍니다. --help나 -h를 붙여도 같은 도움말이 나옵니다.

공통 옵션

서비스 실행과 중지

butler start
butler status
butler logs --lines 200
butler stop

로그 보기

butler start로 시작한 서비스의 출력은 데이터 폴더의 logs/butler-agent-service.stdout.log와 logs/butler-agent-service.stderr.log에 기록됩니다.

설치 점검: doctor

butler doctor는 설치 파일과 데이터 폴더, 실행 중인 서비스를 읽기 전용으로 점검합니다. 문제를 고치지는 않습니다.

butler doctor
butler doctor --check installation
butler doctor --check service --json

--check로 점검 범위를 한 가지만 고를 수 있습니다.

각 항목은 PASS, WARN, FAIL 중 하나로 표시됩니다. 모든 항목이 PASS이면 healthy와 종료 코드 0을, 하나라도 아니면 degraded와 종료 코드 1을 반환합니다.

모델과 인증

butler auth status
butler model list
butler model status

설정

설정은 데이터 폴더의 butler.config.json에 저장됩니다. 키는 점(.)으로 구분한 경로로 지정합니다.

butler config get system.defaultModel
butler config validate

기타 명령

외부 MCP 서버는 옵션으로 등록합니다. 연결 방식(--transport)은 stdio, http, sse 중 하나이며 기본값은 stdio입니다.

butler mcp add --id docs --transport http --url https://example.com/mcp
butler mcp test docs

데이터와 설정 위치

데이터 폴더(기본값 ~/.butler)에는 다음이 저장됩니다.

• butler.config.json: 설정 파일입니다.
• .env: API 키 같은 비밀값입니다.
• auth/openai-codex.json: OAuth 로그인 프로필의 기본 위치입니다.
• logs/: 서비스 로그입니다.

설치 폴더(예: ~/.local/opt/butler-agent/0.0.21)는 실행 중에 바뀌지 않습니다. 파일을 직접 수정하지 않습니다.

업데이트

Butler는 설치된 버전을 바꾸거나 데이터를 옮기지 않습니다. 새 버전은 이전 버전 옆에 따로 설치합니다.

주의 사항

관련 문서