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：

以下のいずれかのコマンドを選択してください。最初のコマンドはファイル削除前に確認を求め、2 番目のコマンドは --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、~/.local/bin/obsycli、および現在の HOME と SUDO_USER ホーム配下の ~/.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 の Web ページからユーザー 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 はトグルです：

• 初回使用時：フルアクセスに入ります。Agent は作業ディレクトリ外のファイルにアクセスでき、ツール呼び出しの承認が不要になります。
• 2 回目の使用時：通常モードに戻り、ファイルアクセス制限と承認プロンプトが復元されます。

YOLO は現在の Agent と Task のコンテキストを信頼できる場合にのみ有効にしてください。

サブエージェントによる作業分割¶

タスクを独立した部分に分割できる場合、/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 [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]

通常のメッセージは自動的にプランモードに入りません。アクティブなプランがある 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 にはエージェントが返す生の 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 で終了します。フルアクセスのリスクを明示的に受け入れる場合にのみ --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 はプランモードをサポートしていません。プランには複数回の確認が必要なためです。プランの承認や修正には対話型の obscli を使用してください。

一般的な終了コード：

--json モードでは、失敗時に stdout は空のままで、stderr は error.code と error.message を含む JSON オブジェクトを返します。スクリプトは終了コードとこれらのフィールドを使用して結果を判定してください。

メッセージ内でのリソースと Skill の参照¶

対話型入力で @ を入力すると、現在のワークスペースの観測リソースを参照できます：

• Service
• Dashboards
• Application
• Hosts
• Containers

矢印キーまたは Tab で閲覧し、Space で 1 つ以上のアイテムを選択し、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 が 1 つの場合、メッセージはその 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

ログは自動的にローテーションされます。1 つのログファイルのデフォルト最大サイズは 32 MiB です。

トラブルシューティング¶

ログインに失敗した場合は、以下を確認してください：

• --beak-server が Beak サービスのアドレスを指していること。
• インストーラー経由でログインする場合、--beak-server が Beak サービスのアドレスを指していること。
• ユーザー sk が現在の Beak Web ページからコピーした有効な認証情報であること。
• HTTPS テスト環境で --insecure-skip-tls-verify が必要かどうか。

チャットに入った後に Task がない場合は、以下を実行してください：

/agents
/newtask <number>

ここで <number> は /agents の # 列に表示される番号です。