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.
5. Use private mode to chat with the local Agent after logging in to its node or container.

Install obscli¶

Install from Settings Center (recommended)¶

On the Obsy Agent Teams page, click your avatar in the upper-right corner and open Personal Configuration > Developer Tools > obs-cli:

1. Select macOS, Linux, or Windows.
2. Click Copy command.
3. Run the command in the terminal where you will use obscli.
4. Run obscli after installation and confirm that Agents in your current workspace are visible.

The generated command includes the account information needed to connect; no manual copy of personal access credentials is required.

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 <YOUR-USER-SK> --beak-server https://agent-api.guance.com

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

obscli --login <YOUR-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.

Chat privately with the local Agent¶

On a Linux or macOS node that runs obs-agent, or inside its container, private mode uses a Unix socket. The Agent keeps its Beak connection, Profile synchronization, heartbeats, and ordinary Web, IM, and CLI sessions.

Log in with your personal credential. Ordinary and private modes share this login configuration. Private mode does not automatically use Agent or administrator credentials:

obscli --login <YOUR-USER-SK> --beak-server https://agent-api.guance.com
obscli --private

A local obs-agent must be running. The default socket is /var/lib/obs-agent/private.sock. A missing socket, failed connection, or access denial causes an error; the client does not switch to a remote Agent. Native Windows is not supported.

Use separate configuration directories for different personal identities under the same operating system account:

obscli --login <YOUR-USER-SK> --beak-server https://agent-api.guance.com --config-dir ~/obscli-personal
obscli --private --config-dir ~/obscli-personal

Differences from ordinary mode¶

Session lists stay separate. A Task ID from another mode cannot attach across modes. Private Tasks remain private when you switch modes or exit. Streaming, reasoning, tool approval, cancellation, and reconnect replay remain available. Private work also uses upgrade idle protection.

Session storage and recovery¶

The local Agent owns private Tasks by personal identity. Accepted work continues after obscli exits; approvals wait for reconnection. Log in with the same identity and connect to the same Agent to recover your history. Agent restart loads local history, but unfinished runs become failed. It does not rerun tools or execute old pending approvals.

AGENT_PRIVATE_DATA_DIR selects the private data directory. By default, it is AGENT_PROFILE_CACHE_DIR plus -private, for example /var/lib/obs-agent/profile-cache-private.

obscli keeps a separate cache at private/<connection-scope-id>/ under its configuration directory, normally ~/.obscli/private/. --config-dir changes that location. This client cache is separate from Agent data. Back up the Agent private data directory to preserve sessions.

Services still accessed¶

On first connection and reconnection, the Agent asks Beak to verify personal identity and local Agent access. New connections fail if Beak is unreachable. Existing connections and accepted work do not automatically stop during a temporary authentication outage, but personal token expiry ends the connection.

The client can still read @ resource and $ Skill lists from Beak. These queries contain no private messages, drafts, or session IDs. Selected entries travel with messages through the local socket. Normal Profile synchronization continues; private runs use ready Skills and MCP settings.

Configured model services and external tools still receive the inputs required for work. Private mode is not a separate operating system sandbox. Users sharing an operating system account may still read files that account can access.

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.

Read-only IM inspection¶

In ordinary mode, workspace owners and wsAdmins can use /tasks to list ordinary IM sessions and IM Bot main conversations and subtasks within their management permissions. Use /attach <number> to view messages, attachments, and tool history. Ordinary members cannot use this view. Private mode does not include these sessions.

The client shows a read-only notice. You can browse history and switch sessions, but cannot send messages, approve actions, cancel or close tasks, change models, or change other session settings. Handle approvals and task actions in the original IM chat under the requester's permissions. This view does not provide Web Bot interaction.

Select a model and reasoning level¶

Run /model after entering a Task to select Auto, Fast, Standard, Pro, or a specific model supported by the Agent. The menu shows model descriptions and multipliers. Models with reasoning settings offer supported levels or a toggle, with their default level preselected. Canceling either menu saves no change.

You can also enter /model Vendor/Model-A high or /model Vendor/Model-A off. Specific model IDs are case-sensitive; the menu lists supported reasoning levels. The four fixed modes still use auto, auto:fast, auto:standard, and auto:advanced and do not accept manual reasoning parameters.

Reattaching restores the Task's model and reasoning settings. New Tasks inherit the account's most recent explicit choice in the current workspace. If a model is temporarily unavailable, the menu retains the selection and indicates that the current turn uses Auto. Catalog failures offer retry while leaving fixed modes available.

The status line uses model <selected-name>(R:<levels>) -> <true-provider-name>, for example model MiniMax-M3.1-Flash-Preview(R:on) -> MiniMax/MiniMax-M3.1-Flash-Preview. The left side shows the selected model and reasoning setting, such as on, off, low, high, or max; the right side shows the actual provider model returned in the response after AIHub name mapping. Only the left side appears before an actual model name is received. (R:...) is omitted without a manual reasoning setting.

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 <YOUR-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'

Before creating a Task, run checks that the Agent exists in the selected workspace and is accessible to the current account. Missing Agents or Agents in another workspace fail immediately with a selection prompt. In --json, the error code is agent_not_found and the exit code is 2. Authentication, network, or service failures also stop before Task creation. Registered Agents that are temporarily offline can still receive tasks; the command waits for recovery and a reply within its timeout.

To select a model and reasoning level:

obscli run --agent-uuid <AGENT_UUID> --model <MODEL_ID> --reasoning high --prompt 'Analyze the current status'

--reasoning supports the model's available levels or on and off, and requires a specific model ID. Omitting reasoning uses that model's default behavior; omitting the model lets the server inherit the most recent explicit complete selection. obscli chat supports the same --model and --reasoning options.

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 -

The normalized prompt is the default Task title. Scripts can set a separate title with --title. This title is not added to the prompt sent to the Agent:

printf '%s\n' '分析最近两小时的错误日志' | \
  obscli run --agent-uuid <AGENT_UUID> --title gceval-l4-log-pattern --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.

obscli run defaults to a 2-hour end-to-end timeout covering task preparation, prompt submission, and the final reply; change it with --timeout 90s. This limit applies to one run command, not interactive chat. Individual model requests and tool executions retain their own timeout settings. 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.

Credential forms also support these cancellation keys while waiting for the network. Input and pasted text during this wait are discarded, so secrets do not enter ordinary chat drafts, logs, or caches.

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.

In ordinary mode, 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. Private mode uses a separate cache; see Session storage and recovery. It retrieves history from the local Agent. In ordinary mode, 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. Each string value longer than 120 Unicode characters (runes) is shortened separately to head (x omitted...) tail, where x is the actual number of omitted runes. The preview stays within 120 runes, preserves the first 60, and adjusts the tail for the omission notice. Other arguments remain complete and the JSON object is not cropped as a whole. Ctrl+T shows complete arguments and results while sensitive values remain hidden. Older saved summaries missing full text retain an explanatory notice. 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.

Local Diagnostic Reports¶

Use obscli bug-report view ./report.zip to open a fully offline diagnostic Viewer. Add --no-open to avoid launching a browser; the service listens only on a random loopback port. See Local Bug Report Viewer.