obscli User Manual¶

obscli is the Beak command-line client. After installing and logging in, you can:

1. View Agents in the current workspace.
2. Create a new Task or continue an existing Task.
3. Chat with Agents, reference observation resources, and select Skills.
4. Submit one-shot tasks from scripts and collect the results.

Install obscli¶

Install with the installer script¶

Linux and macOS¶

Run:

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 use Unix paths by default:

If obscli is not available after installation, add the install directory to PATH:

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

WSL is a Linux environment and uses the same command and paths.

Windows PowerShell¶

Run:

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 installs obscli to this path by default:

%LOCALAPPDATA%\Programs\obscli\obscli.exe

After installation, reopen PowerShell and run:

obscli

If you cannot reopen PowerShell, run the full path directly:

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

Windows default directories:

PowerShell is recommended on Windows. Git Bash interprets paths using its own $HOME; if you use Git Bash, specify the install directory explicitly:

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>

Install with an offline package¶

Download the package that matches your system, for example:

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

Verify and install:

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

Uninstall obscli¶

Migrate from the legacy name before reinstalling¶

If the legacy obsycli is installed on this machine, do not overwrite it directly with obscli. Delete the old executable and old data directory first, then reinstall and log in to the new obscli by following the installation section.

Linux/macOS/WSL:

Choose one command. The first asks for confirmation before deleting files; the second uses --yes to skip confirmation:

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

This script cleans up the fixed system layout from before the rename from beak-agent. It also removes common Linux/macOS install locations for the old obsycli: /usr/local/bin/obsycli, /usr/bin/obsycli, and ~/.local/bin/obsycli plus ~/.obsycli under the current HOME and the SUDO_USER home.

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

After removing the old version, reinstall with the obscli installation commands in this document. obscli uses ~/.obscli or %USERPROFILE%\.obscli and does not read local configuration from the old obsycli.

Uninstall the current version¶

Linux/macOS:

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

If you installed to a system directory with 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

If obscli.exe was placed in another directory, delete the file shown by 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

The local data directory contains login tokens, update config, and logs. After deleting it, you need to log in again.

Log in to Beak¶

Copy the user sk from the Beak web page, then run:

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

If the test environment certificate is not trusted by your machine, add:

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

After a successful login, credentials are written to:

~/.obscli/login.toml

Run obscli directly afterward to enter interactive chat.

How obscli updates automatically¶

When installed with the installer, obscli checks for new versions during startup. When a new version is available, it prompts:

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

After you enter y or yes, obscli downloads the package for the current system, verifies .sha256, and replaces the local executable. Linux/macOS restart obscli automatically after the update. Windows completes replacement after the current process exits, and you need to run obscli again.

To disable startup update checks in the current environment, set:

export OBSCLI_NO_UPDATE_CHECK=1

Common Commands¶

<number> in the table refers to the temporary number in the # column from /agents or /tasks. /newtask <number> uses the # number from /agents; /attach <number> and /close <number> use the # number from /tasks.

Closed Tasks cannot receive new messages. To continue a conversation, create a new Task.

Control Agent access¶

/yolo is a toggle:

• First use: enter Full access. The Agent can access files outside the working directory, and tool calls no longer request approval.
• Second use: return to normal mode and restore file access limits and approval prompts.

Enable YOLO only when you trust the current Agent and Task context.

Split work across subagents¶

When a task can be split into independent parts, use /subagent <task> to ask the Agent to use subagents first. For example:

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

obscli displays each subagent's start, wait, and completion status. The main Agent summarizes the final result. You can recall the complete command from input history with the arrow keys.

Compact task history manually¶

When a long-running task approaches the model context limit, Agent automatically compacts older conversation and tool interactions. To free context space earlier, run this command in the current Task:

/compact

Compaction retains recent raw interactions and converts older history into a continuation summary. It does not close the Task or delete the complete session event record. obscli displays the start and completion status. If the current history is still within the retention budget, Agent reports that compaction is not needed.

Plan and execute complex work¶

Use /plan to enter Plan mode:

/plan [prompt]

For example:

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

After receiving the plan, approve it, reject it, request changes, or interrupt it:

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

Regular messages do not enter Plan mode automatically. Closing a Task with an active plan also interrupts the plan.

Run a single prompt from a script¶

Use obscli run to submit a one-shot task, wait for the Agent's answer, and exit. It is intended for shell scripts and automation.

Log in with obscli --login <user-sk> first. run reads the existing login configuration, so scripts do not need to pass credentials again.

Run obscli -h or obscli run -h to see all supported run options.

If you do not know the agent UUID, list online agents in the current workspace:

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

The default output includes each Agent's UUID, name, and status. Use --json for scripts. This command only queries online Agents and does not create a Task.

Pass a prompt directly:

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

Read a multiline file or 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 -

By default, stdout contains only the raw Markdown returned by the agent and normal progress does not write to stderr. Use --json for a structured result:

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

The JSON result includes the answer, related UUIDs, Agent UUID, and Task name. Usage and attachment information is also returned when available.

The default timeout is 5 minutes; change it with --timeout 90s. Use -v, -vv, -vvv, or --verbose=1|2|3 to write different levels of diagnostic information to stderr. By default, if the Agent requests approval for a dangerous tool, the command cancels the turn and exits with code 3. Use --yolo only when you explicitly accept Full access risk.

To ask a one-shot task to prioritize subagents, add --subagent:

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

If the task cannot reasonably be split, the Agent explains why and answers directly. --subagent cannot be combined with --list-agents.

obscli run does not support Plan mode because plans require multiple rounds of confirmation. Use interactive obscli to approve or revise a plan.

Common exit codes:

In --json mode, stdout remains empty on failure and stderr returns a JSON object containing error.code and error.message. Scripts should use the exit code and these fields to determine the result.

Reference resources and Skills in a message¶

Enter @ in the interactive input to reference observation resources in the current workspace:

• Service
• Dashboards
• Application
• Hosts
• Containers

Use the arrow keys or Tab to browse, Space to select one or more items, and Enter to confirm. Type to search resource names and types. Selected resources appear as @resource-name and provide query context to the Agent.

In an attached single-Agent Task, enter $ to select a Skill provided by that Agent. Search matches the Skill name and description and ignores spaces, so rootcause can match Root cause analysis. Selection works the same way as the resource list, and every selected Skill applies to the whole message.

Both lists require Space to select before Enter confirms. Searching does not clear existing selections.

At the boundary of @resource-name or $skill-name, Backspace or Delete removes the entire reference. Recalling a message with the arrow keys or Ctrl+R also restores its resources and Skills.

To enter a literal @ or $, press Esc after the list opens. Pasted @ and $ also remain plain text.

After opening a Task, type a message and press Enter. If the Task has one Agent, the message goes to that Agent. If it has multiple Agents, the message is broadcast to all of them.

Use keyboard shortcuts¶

Normal input supports these shortcuts:

Normal input:

Pop-up selection:

If arrow keys or control keys do not work in a terminal, first check whether the terminal has bound the shortcut to an outer application. If the issue remains, open ~/.obscli/log/obscli.log and record the terminal name, version, and key behavior.

Local Files¶

obscli uses the following local paths by default:

Linux/macOS:

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

Windows:

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

Logs rotate automatically. The default maximum size for one log file is 32 MiB.

Troubleshooting¶

When login fails, check:

• --beak-server points to the Beak service address.
• If you log in through the installer, --beak-server points to the Beak service address.
• The user sk is a valid credential copied from the current Beak web page.
• Whether the HTTPS test environment requires --insecure-skip-tls-verify.

If there is no task after entering chat, run:

/agents
/newtask <number>

Here, <number> is the number in the # column from /agents.