obscli 사용자 매뉴얼¶

obscli는 Beak 명령줄 클라이언트입니다. 설치 및 로그인 후 다음을 수행할 수 있습니다:

1. 현재 워크스페이스의 Agent를 조회합니다.
2. 새 Task를 생성하거나 기존 Task를 계속합니다.
3. Agent와 대화하고, 관측 리소스를 참조하며, Skill을 선택합니다.
4. 스크립트에서 일회성 작업을 제출하고 결과를 수집합니다.

obscli 설치¶

설치 스크립트로 설치¶

Linux 및 macOS¶

실행:

curl -fsSL https://static.guance.com/obscli/install-obscli.sh | bash -s -- \
  --release-base-url https://static.guance.com/obscli \
  --beak-server https://agent-api.guance.com \
  --login <YOUR-USER-SK>

Linux/macOS는 기본적으로 Unix 경로를 사용합니다:

설치 후 obscli를 사용할 수 없는 경우, 설치 디렉터리를 PATH에 추가하세요:

export PATH="$HOME/.local/bin:$PATH"

WSL은 Linux 환경이므로 동일한 명령과 경로를 사용합니다.

Windows PowerShell¶

실행:

iwr https://static.guance.com/obscli/install-obscli.ps1 -OutFile $env:TEMP\install-obscli.ps1
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& $env:TEMP\install-obscli.ps1 `
  -ReleaseBaseUrl https://static.guance.com/obscli `
  -BeakServer https://agent-api.guance.com `
  -Login <YOUR-USER-SK>

Windows에서 obscli는 기본적으로 다음 경로에 설치됩니다:

%LOCALAPPDATA%\Programs\obscli\obscli.exe

설치 후 PowerShell을 다시 열고 실행하세요:

obscli

PowerShell을 다시 열 수 없는 경우, 전체 경로를 직접 실행하세요:

& "$env:LOCALAPPDATA\Programs\obscli\obscli.exe"

Windows 기본 디렉터리:

Windows에서는 PowerShell을 권장합니다. Git Bash는 자체 $HOME을 사용하여 경로를 해석합니다. Git Bash를 사용하는 경우 설치 디렉터리를 명시적으로 지정하세요:

curl.exe -fsSL https://static.guance.com/obscli/install-obscli.sh | bash -s -- \
  --release-base-url https://static.guance.com/obscli \
  --install-dir "$HOME/bin" \
  --beak-server https://agent-api.guance.com \
  --login <YOUR-USER-SK>

오프라인 패키지로 설치¶

시스템에 맞는 패키지를 다운로드합니다. 예:

obscli-linux-amd64-v1.2.3.tar.gz
obscli-darwin-arm64-v1.2.3.tar.gz
obscli-windows-amd64-v1.2.3.tar.gz

검증 및 설치:

sha256sum -c obscli-linux-amd64-v1.2.3.tar.gz.sha256
bash install-obscli.sh --archive ./obscli-linux-amd64-v1.2.3.tar.gz --install-dir "$HOME/.local/bin" --yes

obscli 제거¶

재설치 전 이전 이름에서 마이그레이션¶

이 머신에 이전 obsycli가 설치되어 있는 경우, obscli로 직접 덮어쓰지 마세요. 먼저 이전 실행 파일과 데이터 디렉터리를 삭제한 후, 설치 섹션에 따라 새 obscli를 재설치하고 로그인하세요.

Linux/macOS/WSL:

명령 중 하나를 선택하세요. 첫 번째는 파일 삭제 전 확인을 요청하고, 두 번째는 --yes를 사용하여 확인을 건너뜁니다:

curl -fsSL https://static.guance.com/obs-agent/uninstall-legacy.sh | sudo bash
curl -fsSL https://static.guance.com/obs-agent/uninstall-legacy.sh | sudo bash -s -- --yes

이 스크립트는 beak-agent에서 이름이 변경되기 전의 고정 시스템 레이아웃을 정리합니다. 또한 이전 obsycli의 일반적인 Linux/macOS 설치 위치도 제거합니다: /usr/local/bin/obsycli, /usr/bin/obsycli, 그리고 현재 HOME 및 SUDO_USER 홈 아래의 ~/.local/bin/obsycli와 ~/.obsycli입니다.

Windows PowerShell:

Get-Command obsycli -All
Remove-Item "$env:LOCALAPPDATA\Programs\obsycli\obsycli.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\obsycli" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.obsycli" -Recurse -Force -ErrorAction SilentlyContinue

이전 버전을 제거한 후 이 문서의 obscli 설치 명령으로 재설치하세요. obscli는 ~/.obscli 또는 %USERPROFILE%\.obscli를 사용하며 이전 obsycli의 로컬 설정을 읽지 않습니다.

현재 버전 제거¶

Linux/macOS:

which -a obscli
rm -f ~/.local/bin/obscli
rm -rf ~/.obscli

sudo로 시스템 디렉터리에 설치한 경우:

sudo rm -f /usr/local/bin/obscli
rm -rf ~/.obscli

Windows PowerShell:

Get-Command obscli -All
Remove-Item "$env:LOCALAPPDATA\Programs\obscli\obscli.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\obscli" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.obscli" -Recurse -Force -ErrorAction SilentlyContinue

obscli.exe가 다른 디렉터리에 있는 경우, Get-Command obscli -All로 표시된 파일을 삭제하세요.

Windows Git Bash:

which -a obscli
rm -f "$HOME/bin/obscli.exe"
rm -rf "$HOME/.obscli"

WSL:

which -a obscli
rm -f ~/.local/bin/obscli
rm -rf ~/.obscli

로컬 데이터 디렉터리에는 로그인 토큰, 업데이트 설정, 로그가 포함되어 있습니다. 삭제 후에는 다시 로그인해야 합니다.

Beak에 로그인¶

Beak 웹 페이지에서 사용자 sk를 복사한 후 실행하세요:

obscli --login <user-sk> --beak-server https://agent-api.guance.com

테스트 환경 인증서가 머신에서 신뢰되지 않는 경우 다음을 추가하세요:

obscli --login <user-sk> --beak-server https://agent-api.guance.com --insecure-skip-tls-verify

로그인이 성공하면 자격 증명이 다음에 저장됩니다:

~/.obscli/login.toml

이후 obscli를 직접 실행하면 대화형 채팅에 진입합니다.

obscli 자동 업데이트 방식¶

설치 스크립트로 설치한 경우, obscli는 시작 시 새 버전을 확인합니다. 새 버전이 있으면 다음과 같이 안내합니다:

New obscli version available: v1.2.3 -> v1.2.4. Update now? [y/N]

y 또는 yes를 입력하면 obscli는 현재 시스템용 패키지를 다운로드하고, .sha256을 검증한 후 로컬 실행 파일을 교체합니다. Linux/macOS는 업데이트 후 obscli를 자동으로 재시작합니다. Windows는 현재 프로세스가 종료된 후 교체가 완료되므로 obscli를 다시 실행해야 합니다.

현재 환경에서 시작 시 업데이트 확인을 비활성화하려면 다음을 설정하세요:

export OBSCLI_NO_UPDATE_CHECK=1

주요 명령어¶

표에서 <number>는 /agents 또는 /tasks의 # 열에 표시되는 임시 번호를 의미합니다. /newtask <number>는 /agents의 # 번호를 사용하고, /attach <number> 및 /close <number>는 /tasks의 # 번호를 사용합니다.

닫힌 Task는 새 메시지를 받을 수 없습니다. 대화를 계속하려면 새 Task를 생성하세요.

Agent 접근 제어¶

/yolo는 토글입니다:

• 첫 번째 사용: Full access 모드 진입. Agent가 작업 디렉터리 외부의 파일에 접근할 수 있으며, 도구 호출 시 승인을 요청하지 않습니다.
• 두 번째 사용: 일반 모드로 복귀하여 파일 접근 제한 및 승인 프롬프트를 복원합니다.

현재 Agent와 Task 컨텍스트를 신뢰하는 경우에만 YOLO를 활성화하세요.

하위 에이전트로 작업 분할¶

작업을 독립적인 부분으로 나눌 수 있는 경우, /subagent <task>를 사용하여 Agent에게 먼저 하위 에이전트를 활용하도록 요청합니다. 예:

/subagent Check error logs, slow queries, and alert events from the past hour separately, then summarize root-cause clues

obscli는 각 하위 에이전트의 시작, 대기 및 완료 상태를 표시합니다. 메인 Agent가 최종 결과를 요약합니다. 방향키로 입력 기록에서 전체 명령을 불러올 수 있습니다.

복잡한 작업의 계획 및 실행¶

/plan을 사용하여 Plan 모드에 진입합니다:

/plan [prompt]

예:

/plan I want to build a dashboard. Please create a plan.

계획을 받은 후 승인, 거부, 수정 요청 또는 중단할 수 있습니다:

/plan-approve
/plan-approve /subagent [instruction]
/plan-reject [reason]
/plan-revise <feedback>
/plan-interrupt [reason]

일반 메시지는 자동으로 Plan 모드에 진입하지 않습니다. 활성 계획이 있는 Task를 닫으면 해당 계획도 중단됩니다.

스크립트에서 단일 프롬프트 실행¶

obscli run을 사용하여 일회성 작업을 제출하고 Agent의 응답을 기다린 후 종료합니다. 셸 스크립트 및 자동화에 사용됩니다.

먼저 obscli --login <user-sk>로 로그인하세요. run은 기존 로그인 설정을 읽으므로 스크립트에서 자격 증명을 다시 전달할 필요가 없습니다.

obscli -h 또는 obscli run -h를 실행하여 지원되는 모든 run 옵션을 확인하세요.

Agent UUID를 모르는 경우 현재 워크스페이스의 온라인 Agent를 조회하세요:

obscli run --list-agents
obscli run --list-agents --json

기본 출력에는 각 Agent의 UUID, 이름, 상태가 포함됩니다. 스크립트에서는 --json을 사용하세요. 이 명령은 온라인 Agent만 조회하며 Task를 생성하지 않습니다.

프롬프트 직접 전달:

answer="$(obscli run --agent-uuid <AGENT_UUID> --prompt 'Check errors from the past hour and summarize them briefly')"
printf '%s\n' "$answer"

여러 줄의 파일 또는 stdin 읽기:

obscli run --agent-uuid <AGENT_UUID> --prompt-file ./prompt.md
printf '%s\n' 'Summarize the health of the current workspace' | \
  obscli run --agent-uuid <AGENT_UUID> --prompt-file -

기본적으로 stdout에는 Agent가 반환한 원시 Markdown만 포함되며 정상 진행 상황은 stderr에 기록되지 않습니다. 구조화된 결과를 얻으려면 --json을 사용하세요:

obscli run --agent-uuid <AGENT_UUID> --prompt 'Return a one-line status summary' --json

JSON 결과에는 응답, 관련 UUID, Agent UUID, Task 이름이 포함됩니다. 사용량 및 첨부 파일 정보도 가능한 경우 반환됩니다.

기본 타임아웃은 5분이며 --timeout 90s로 변경할 수 있습니다. -v, -vv, -vvv 또는 --verbose=1|2|3을 사용하여 다양한 수준의 진단 정보를 stderr에 기록합니다. 기본적으로 Agent가 위험한 도구에 대한 승인을 요청하면 해당 턴을 취소하고 종료 코드 3으로 종료합니다. Full access 위험을 명시적으로 수락하는 경우에만 --yolo를 사용하세요.

일회성 작업에서 하위 에이전트를 우선 사용하도록 하려면 --subagent를 추가하세요:

obscli run --agent-uuid <AGENT_UUID> --subagent \
  --prompt 'Check errors, slow queries, and alerts from the past hour separately, then summarize the evidence'

작업을 합리적으로 분할할 수 없는 경우, Agent가 이유를 설명하고 직접 응답합니다. --subagent는 --list-agents와 함께 사용할 수 없습니다.

obscli run은 Plan 모드를 지원하지 않습니다. 계획은 여러 차례의 확인이 필요하기 때문입니다. 계획을 승인하거나 수정하려면 대화형 obscli를 사용하세요.

주요 종료 코드:

--json 모드에서 실패 시 stdout은 비어 있으며 stderr에 error.code 및 error.message를 포함하는 JSON 객체가 반환됩니다. 스크립트는 종료 코드와 이 필드를 사용하여 결과를 판별해야 합니다.

메시지에서 리소스 및 Skill 참조¶

대화형 입력에서 @를 입력하면 현재 워크스페이스의 관측 리소스를 참조할 수 있습니다:

• Service
• Dashboards
• Application
• Hosts
• Containers

방향키 또는 Tab으로 탐색하고, Space로 하나 이상의 항목을 선택한 후 Enter로 확인합니다. 입력하면 리소스 이름과 유형을 검색할 수 있습니다. 선택된 리소스는 @resource-name으로 표시되며 Agent에 쿼리 컨텍스트를 제공합니다.

단일 Agent Task에 연결된 상태에서 $를 입력하면 해당 Agent가 제공하는 Skill을 선택할 수 있습니다. 검색은 Skill 이름과 설명을 매칭하며 공백을 무시하므로, rootcause로 Root cause analysis를 검색할 수 있습니다. 선택 방식은 리소스 목록과 동일하며, 선택된 모든 Skill은 전체 메시지에 적용됩니다.

두 목록 모두 Enter로 확인하기 전에 Space로 선택해야 합니다. 검색해도 기존 선택은 유지됩니다.

@resource-name 또는 $skill-name의 경계에서 Backspace 또는 Delete를 누르면 전체 참조가 삭제됩니다. 방향키 또는 Ctrl+R로 메시지를 불러오면 리소스와 Skill도 함께 복원됩니다.

리터럴 @ 또는 $를 입력하려면 목록이 열린 후 Esc를 누르세요. 붙여넣은 @ 및 $도 일반 텍스트로 유지됩니다.

Task를 연 후 메시지를 입력하고 Enter를 누르세요. Task에 Agent가 하나인 경우 해당 Agent에게 메시지가 전송됩니다. 여러 Agent가 있는 경우 모든 Agent에게 메시지가 브로드캐스트됩니다.

키보드 단축키 사용¶

일반 입력에서 지원하는 단축키:

일반 입력:

팝업 선택:

터미널에서 방향키 또는 제어 키가 작동하지 않는 경우, 먼저 터미널이 해당 단축키를 외부 애플리케이션에 바인딩했는지 확인하세요. 문제가 지속되면 ~/.obscli/log/obscli.log를 열고 터미널 이름, 버전, 키 동작을 기록하세요.

로컬 파일¶

obscli는 기본적으로 다음 로컬 경로를 사용합니다:

Linux/macOS:

~/.obscli/login.toml
~/.obscli/log/obscli.log

Windows:

%USERPROFILE%\.obscli\login.toml
%USERPROFILE%\.obscli\log\obscli.log

로그는 자동으로 로테이션됩니다. 단일 로그 파일의 기본 최대 크기는 32 MiB입니다.

문제 해결¶

로그인 실패 시 다음을 확인하세요:

• --beak-server가 Beak 서비스 주소를 가리키는지 확인합니다.
• 설치 스크립트를 통해 로그인하는 경우, --beak-server가 Beak 서비스 주소를 가리키는지 확인합니다.
• 사용자 sk가 현재 Beak 웹 페이지에서 복사한 유효한 자격 증명인지 확인합니다.
• HTTPS 테스트 환경에 --insecure-skip-tls-verify가 필요한지 확인합니다.

채팅 진입 후 Task가 없는 경우 다음을 실행하세요:

/agents
/newtask <number>

여기서 <number>는 /agents의 # 열에 표시되는 번호입니다.