obscli User Manual¶

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

1. View every workspace, Agent, and Task available to the account.
2. Create a new Task or continue an existing Task in the selected workspace.
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.

Both /agents and /tasks include a workspace column. After /newtask <number> or /attach <number>, the current Session switches to the corresponding workspace; messages, approvals, history, attachments, @ resources, and $ Skills continue to use that workspace. Closing the current Task returns to the default workspace in the login configuration. The footer uses the separate workspace item for the current workspace and agent_task for the Agent/Task; both can be adjusted with /statusline.

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.

Copy the final answer¶

Run /copy in the current Task to copy the most recent completed LLM final answer, as raw Markdown, to the system clipboard of the machine running obscli:

/copy

/copy accepts no arguments and copies only the final answer. It excludes thinking, commentary, tool calls, Task Insights, subagent handoffs, and other runtime details. A plan_final also counts as a copyable final answer. To collect diagnostic context, ask the Agent to use collect_bug_report instead of exporting runtime details through the clipboard.

If the latest turn has not produced a final answer, obscli copies the previous completed answer and displays a warning.

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.

Tasks that need temporary credentials can use --import-credential /secure/credentials.json to import text and files. The prompt is sent only after every upload is confirmed; completing the task closes the session and revokes credentials. See Private Session Credentials for formats and paths. Do not put secrets in the prompt.

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 available Agents across the account's workspaces:

obscli run --list-agents
obscli run --list-agents --json
obscli run --list-agents --workspace-uuid <WORKSPACE_UUID>

The default output includes the workspace, Agent UUID, name, and raw creating, idle, busy, or offline status. --json also includes workspace_uuid and workspace_name for scripts. With --workspace-uuid, obscli still reads the account-level list first and filters it in the client. This command 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"

By default, the Task is created in the workspace from the login configuration. To run in another workspace, specify it explicitly:

obscli run --workspace-uuid <WORKSPACE_UUID> --agent-uuid <AGENT_UUID> --prompt 'Check the current status'

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 Session 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:

While a slash command waits for Beak, press Ctrl+C or Esc twice to stop waiting locally. Text entered during the wait stays as a draft and requires a new Enter to submit. Canceling does not undo completed server operations; if a write may already have taken effect, check its status before retrying.

While waiting for the service response, press Ctrl+C or Esc twice to cancel the wait. Input and pasted text during the wait are discarded and do not enter chat drafts, logs, or caches. Canceling a write already sent does not undo the server operation; check the result before retrying.

In tool details, use arrow keys or the mouse wheel to scroll, PageUp/PageDown to change pages, Home/End to reach the beginning/end, and Ctrl+P/Ctrl+N to navigate calls. Opening the viewer selects the beginning of the latest call. Typing, paste, and Enter do not edit or submit chat messages. New results preserve your reading position; scrolling to the end enables following. If approval arrives, return with q to handle it.

Loaded and subsequently received chat content is cached at ~/.obscli/cache/sessions/YYYY/MM/DD/<session-id>.jsonl, even without opening tool details. Each session keeps its original cache date directory across restarts and attach. In an interactive terminal, attach displays recent local chat first, then pages through all available Beak history in the background while you continue typing. With pipe or script input, it finishes loading history before reading the next command, preserving the order of commands such as /save and /exit. Reattaching loads new history from the saved message checkpoint and separately checks Reply Runs that were unfinished before disconnection. Completed calls already synchronized at the same version do not download their details again. Failed synchronization displays History sync incomplete. Reattach or open tool details to retry and continue unfinished history pagination. Older synchronized tool calls remain available in Ctrl+T; normal chat shows recent messages and tool previews.

Within the same session and Agent, each tool_call_id identifies one call. Existing local arguments, commentary, and complete results are retained first. Remote history fills missing content and final states or results produced while offline; redacted summaries do not overwrite complete local text, and terminal states never return to running. Normal chat and Ctrl+T read the same merged records. Conflicting terminal states with no ordering evidence keep the previous state. The SQLite side file stores only JSONL offsets, ordering, deduplication, and synchronization indexes and is rebuilt on every open. Text, provenance, and synchronization checkpoints remain in JSONL. Existing caches need no migration. Switching sessions or exiting cancels background requests. If the cache is not writable, only available history is shown with an explanation. Cache identity checks the server, workspace, user, and session. Unused files that have not changed for 30 days are cleaned up.

Tool details are not limited to 256 KiB per call or the latest 50 calls. Existing Beak redaction, truncation, and reference text remain unchanged. The viewer keeps chat tool headings, separators, and command highlighting, with indented JSON and Markdown formatting retained during scrolling and resizing. Progress feedback and commentary remain available after completion and attach.

Complete arguments require a newer Agent. Older Agents or caches without complete arguments show an unavailable notice and the existing summary. Historical arguments retain Beak's redaction. Line-shortened arguments, commands, commentary, and results use ...+<n> lines (ctrl+t to view transcript).

Tool numbers start at 1 in each session cache, follow first appearance, and remain stable across chat turns and attach. Normal chat hides them by default. /tool-index on|off immediately redraws retained history and active tools, and saves show_tool_index in ~/.obscli/config.toml. Numbers appear as gray (n); batch [i/count] stays separate. Ctrl+T always shows numbers. Press g, enter a number, and press Enter to jump; Esc cancels. Invalid numbers preserve the current position. A jump stops automatic following. Ctrl+P/N still follows chat order. Numbers are stable only within the same local cache; unavailable caches do not generate substitute numbers.

Tool headings show tool names, including read_skill and read_skill_file, with Skill names and paths underneath. Older records without a tool name keep their existing display name.

During reasoning, Thinking... retains the latest five screen lines, wrapping long lines and displaying fragments immediately. Completion leaves a bounded preview; complete events remain cached. Non-interactive output retains all text. Normal chat also previews arguments for concurrent calls and attach history; use Ctrl+T for full content. Cache or history failures show an explicit details-unavailable notice while keeping other content readable.

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.