obsycli User Manual¶

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

Installation¶

Install with Script¶

Linux/macOS:

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

Linux/macOS use Unix paths by default:

Make sure the install directory is in PATH:

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

Windows PowerShell:

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

Windows uses Windows paths by default:

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

obsycli

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\obsycli\obsycli.exe"

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.

The installer writes --release-base-url to the login config file for the current system:

Linux/macOS: ~/.obsycli/login.toml
Windows:     %USERPROFILE%\.obsycli\login.toml

obsycli reads this address on startup to check for new versions.

Uninstallation¶

Linux/macOS:

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

If you installed to a system directory with sudo:

sudo rm -f /usr/local/bin/obsycli
rm -rf ~/.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

If obsycli.exe was placed in another directory, delete the file shown by Get-Command obsycli -All.

Windows Git Bash:

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

WSL:

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

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

Login¶

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

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

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

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

After a successful login, credentials are written to:

~/.obsycli/login.toml

Run obsycli directly afterward to enter interactive chat.

Auto Update¶

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

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

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

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

export OBSYCLI_NO_UPDATE_CHECK=1

Common Commands¶

Closed tasks cannot receive new messages. To continue a conversation, create a new task.

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¶

obsycli 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 ~/.obsycli/log/obsycli.log and record the terminal name, version, and key behavior.

Local Files¶

obsycli uses the following local paths by default:

Linux/macOS:

~/.obsycli/login.toml
~/.obsycli/log/obsycli.log

Windows:

%USERPROFILE%\.obsycli\login.toml
%USERPROFILE%\.obsycli\log\obsycli.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>