obscli User Manual¶

obscli is a command-line client for connecting to the Beak service. You can use it to log in to Beak, list agents and tasks, create or attach to tasks, and chat with agents in the terminal.

Install obscli¶

Install with the installer script¶

Linux/macOS:

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

Linux/macOS use Unix paths by default:

Windows Git Bash can run the Unix shell installer, but paths are interpreted according to Git Bash's $HOME. To install into the Windows user directory, prefer the PowerShell installer. WSL is a Linux environment and uses Linux paths and Linux packages.

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

Windows PowerShell:

iwr https://static.truewatch.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.truewatch.com/obscli `
  -BeakServer https://agent-api.truewatch.com `
  -Login <YOUR-USER-SK>

By default, obscli is installed to ~/.local/bin/obscli. It does not require root privileges and can self-update later.

Make sure the install directory is in PATH:

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

The Windows PowerShell installer uses the user directory by default:

%LOCALAPPDATA%\Programs\obscli\obscli.exe

After updating the user Path, already-open terminals may not refresh the environment automatically. Reopen PowerShell, then run:

obscli

If you started a child process from the current PowerShell window to run the installer, such as powershell -File ..., the parent window's PATH will not be refreshed by the child process. In that case, run the full path printed by the installer:

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

Windows default directories:

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:

curl -fsSL https://static.truewatch.com/obs-agent/uninstall-legacy.sh | sudo bash
curl -fsSL https://static.truewatch.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.truewatch.com

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

obscli --login <user-sk> --beak-server https://agent-api.truewatch.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.

When a task can be split into several independent directions, use /subagent <task> to ask the agent to prioritize session-local subagents. For example:

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

obscli displays subagent start, waiting, and completion status. The final response is still summarized by the main agent. If a subagent fails, times out, or is canceled, the main agent explains that the corresponding result is unavailable or incomplete in the final response.

Plan mode can only be triggered with slash commands. The agent does not automatically enter plan mode from natural-language planning requests. Use:

Example:

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

If the prompt does not contain a plannable task, the agent will ask for clarification.

Sending Messages¶

After attaching to a task, type a natural-language message and press Enter.

If the task has only one agent, the message is sent to that agent by default. If the task has multiple agents, the message is broadcast.

Terminal Keyboard Shortcuts¶

obscli interactive input and pop-up selections support the following keys:

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.