# BossConsole Command Line Interface (CLI)

BossConsole provides a native command-line interface that allows developers and **external AI agents** (Claude Code, Gemini CLI, Aider, custom scripts) to interact directly with the running BossConsole desktop application.

---

## Installation & Setup

When BossConsole is installed, the `boss` executable is placed on your system PATH or accessible via:
- **macOS / Linux**: `boss` (or `/Applications/BOSS.app/Contents/MacOS/boss`)
- **Windows**: `boss.bat` or `boss.ps1` (or in `%LOCALAPPDATA%\Programs\BOSS\boss.bat`)

You can install or update the CLI symlinks inside BossConsole via **Toolbox → Tools → Install BOSS CLI**.

---

## Core Desktop Commands

| Command | Description | Example |
|---|---|---|
| `boss <url>` | Opens a URL in an embedded browser tab | `boss https://github.com` |
| `boss file <path>` | Opens a file in the BossEditor | `boss file src/main.kt` |
| `boss folder <path>` | Opens a project folder in workspace | `boss folder ~/projects/my-app` |
| `boss workspace <file>` | Loads a workspace configuration | `boss workspace ./workspace.json` |
| `boss terminal` | Opens a new integrated BossTerm pane | `boss terminal` |
| `boss status` | Checks running BossConsole health and status | `boss status --json` |
| `boss doctor` | Reports health problems with suggested next steps (exit `2` when degraded) | `boss doctor --json` |
| `boss mcp <action>` | Discovers and invokes MCP tools | `boss mcp list` |
| `boss plugin <action>` | Developer CLI: scaffold, validate, and link plugins | `boss plugin init my-tool` |
| `boss completion <shell>` | Generates shell tab-completion scripts | `boss completion bash > ~/.boss-complete.sh` |

---

## CLI Agent Harness (`boss status` & `boss mcp`)

The packaged executable is required. Set `BOSS_BIN` (macOS/Linux) or `BOSS_EXE` (Windows) for a nonstandard install. These commands do not start the desktop when it is closed.

The **CLI Agent Harness** bridges terminal coding agents directly into the running desktop harness via an authenticated local Unix socket (macOS/Linux) or loopback TCP channel (Windows). Terminal agents can inspect the workspace, drive the browser, run git operations, and trigger automation without running a heavy SSE or WebSocket client.

### 1. `boss status`

Inspects the running BossConsole desktop instance, reporting active project, memory consumption, version, and platform health.

```bash
# Human-readable status report
boss status

# Machine-readable JSON output
boss status --json
```

**JSON Output Example**:
```json
{
  "running": true,
  "version": "9.5.10",
  "os": "Windows 11",
  "arch": "amd64",
  "activeProject": "BossConsole",
  "memory": {
    "usedMb": 412,
    "maxMb": 2048,
    "heapPercent": 20
  }
}
```

#### Health: the `health` field and `boss doctor`

`boss status --json` also carries a `health` object. It reports problems BOSS already tracks but previously showed only inside a window: plugins the sandbox watchdog stopped after repeated failures, plugins that need attention in **Help > Plugin Health & Recovery**, a browser engine that is not installed, could not start, or has stopped responding, and MCP kill-switch or policy faults that withhold tools. The field is additive and `boss status` keeps its existing exit codes; its human output gains a single `Health:` line.

`boss doctor` prints the same report with a suggested next step for each problem, and exits with code `2` while any problem is present. Both commands are read-only: they never change plugin, browser or MCP state. Both also say in words when coverage was incomplete: `Not checked:` for an area nothing could be read from, and `Partially checked:` for one where some sources answered and others failed.

```bash
# Human-readable report: exit 0 when healthy, 2 when degraded, 1 when BOSS is not running
boss doctor

# The health object as JSON, with the same exit codes
boss doctor --json
```

**Health Object Example**:
```json
{
  "degraded": true,
  "findings": [
    {
      "area": "plugins",
      "severity": "warning",
      "code": "plugin_stopped_after_failures",
      "summary": "Plugin 'Terminal Tab' was stopped after repeated failures.",
      "subject": "ai.rever.boss.plugin.dynamic.terminaltab",
      "remedy": "Reload it from Help > Plugin Health & Recovery in the affected window, or restart BOSS."
    }
  ],
  "unchecked": [],
  "partial": []
}
```

- `degraded` is the verdict for the workspace, and is `true` whenever `findings` is non-empty. A reader should not infer health from the findings count alone: a newer BOSS may report `degraded: true` with an empty `findings` list, and both `boss doctor` and the `Health:` line in `boss status` report that as degraded rather than as OK.
- `area` is `plugins`, `browser` or `mcp`.
- `severity` is `critical` when something that should work is broken and a whole capability is gone (a browser engine that failed, or every MCP tool), and `warning` for something narrower: one plugin, one setting that was not saved, or a browser engine that has not been downloaded yet. Critical findings are listed first.
- `code` is stable for scripts to match on: `plugin_stopped_after_failures`, `plugin_needs_attention`, `browser_engine_not_installed`, `browser_engine_unavailable`, `browser_engine_unresponsive`, `mcp_tools_withheld`, `mcp_tool_setting_not_saved`, `mcp_policy_unreadable`, `mcp_policy_not_saved`. `summary` is for people and may be reworded.
- `subject` (a plugin id or tool name) and `remedy` are omitted when they do not apply.
- `unchecked` lists areas whose state could not be read at all, including `plugins` while no BOSS window is open. They are neither healthy nor degraded and do not affect the exit code.
- `partial` lists areas that were read from several sources where some of those sources failed. Today only `plugins` can appear, because it has one source per open window: if one window's source fails, the other windows' findings are still reported and `plugins` is listed here instead of being dropped into `unchecked`. Findings in a partial area are real, but the area is not fully covered, so an empty result there is not a clean bill of health. Like `unchecked`, it does not affect the exit code. An area is never in both `unchecked` and `partial`. The field is additive: a BOSS that predates it simply omits it, and both `boss status` and `boss doctor` treat an absent `partial` as empty.
- Plugin health covers every open window that could be read. A plugin you disabled, or one your role cannot access, is not reported as a problem.

---

### 2. `boss mcp list`

Discovers all registered and accessible MCP tools exposed by BossConsole and its active plugins.

```bash
# List all registered tools
boss mcp list

# Filter tools by keyword (saves agent context tokens)
boss mcp list --filter browser
boss mcp list -f git

# Emit machine-readable JSON array of tools
boss mcp list --json
boss mcp list -f terminal --json
```

---

### 3. `boss mcp describe <tool_name>`

**Token Guardrail**: Dumping 100+ tool schemas into an LLM prompt can consume 15,000+ tokens. `boss mcp describe` prints only the selected tool and its input schema. Discovery currently transfers the accessible registry over local IPC before filtering. Use the exact registered name from `boss mcp list`; client-specific prefixes such as `mcp__boss__` are not part of registry names.

```bash
# Human-readable tool details and required permissions
boss mcp describe browser_navigate

# Machine-readable JSON schema
boss mcp describe browser_navigate --json
```

**Sample Output**:
```
MCP Tool: browser_navigate
Plugin:   fluck-browser
Access:   Standard

Description:
  Navigates the active browser tab to the specified URL.
  Arguments: {"url": "<target_url>"}
```

---

### 4. `boss mcp invoke <tool_name>`

Invokes tools exposed by the host plugin registry. Built-in terminal MCP server tools are a separate surface and are not included. JSON arguments are bounded to 767 KiB so their Base64 framing fits the 1 MiB request limit.

```bash
# 1. Direct arguments with JSON string
boss mcp invoke search_workspace --args '{"query":"SingleInstanceManager"}'

# 2. Raw output mode (-r) for shell scripts and piping
boss mcp invoke git_status -r | grep "modified"

# 3. Piping multi-KB / multiline payloads from standard input
cat query.json | boss mcp invoke run_sql --stdin
echo '{"path": "build.gradle.kts"}' | boss mcp invoke read_file -a -

# 4. Client wait timeout (default: 35 seconds, range: 1-60)
# Server execution is limited to 30 seconds; a shorter client wait does not cancel work.
boss mcp invoke heavy_build -a '{"target":"desktopJar"}' --timeout 60

# 5. Full structured JSON envelope
boss mcp invoke workspace_info --json
```

---

### 5. `boss mcp ledger <verify|tail|search>`

Reads the local, sanitized MCP operation ledger without requiring a running BOSS process.

```bash
# Verify retained hash-chain integrity; exits non-zero for broken, incomplete, or unverifiable data
boss mcp ledger verify

# Show the newest 20 records, or filter the durable history
boss mcp ledger tail -n 20
boss mcp ledger search --tool run_command --disposition failed --from 2026-09-01 --limit 50

# Machine-readable output or an explicit ledger path
boss mcp ledger verify --json
boss mcp ledger tail --file /path/to/mcp-calls.jsonl --json
```

The chain detects edits, insertions, reordering, and removals from inside retained history. It is
not a signature: someone able to rewrite the entire chain can recompute it, and removing only the
newest tail cannot be distinguished from normal retained history without an external checkpoint.
An all-legacy ledger from before integrity tracking exits non-zero until BOSS writes one new record
that anchors the hash chain; the report distinguishes that ordinary upgrade state from tampering.

---

### 6. `boss completion <bash|zsh|fish>`

Generates tab-autocompletion scripts for your shell, completing subcommands and MCP actions (`list`, `describe`, `invoke`):

```bash
# Bash completion setup
boss completion bash > ~/.boss-completion.bash
echo "source ~/.boss-completion.bash" >> ~/.bashrc

# Zsh completion setup
boss completion zsh > ~/.zsh/_boss
echo "source ~/.zsh/_boss" >> ~/.zshrc

# Fish completion setup
boss completion fish > ~/.config/fish/completions/boss.fish
```

---

## Plugin Developer CLI (`boss plugin`)

The `boss plugin` command suite accelerates developing third-party plugins with scaffolding, validation, and hot-linking. See [`docs/PLUGIN_LAUNCHPAD.md`](PLUGIN_LAUNCHPAD.md) for full specifications.

### 1. `boss plugin init <name>`
Scaffolds a new plugin project across templates (`mcp-tool`, `ui-panel`, `background-service`, `full`):
```bash
boss plugin init my-tool --template mcp-tool
boss plugin init my-service --template background-service --dir ~/plugins/my-service --json
```

### 2. `boss plugin validate [<path>]`
Validates a plugin source directory or packaged `.jar` against manifest rules, permitted permissions, and bytecode entrypoints:
```bash
boss plugin validate
boss plugin validate build/libs/my-plugin-0.1.0.jar --json
```

### 3. `boss plugin link [<path>]`
Links the plugin into `$BOSS_HOME/plugins/dev/<plugin-id>`. If BossConsole is running, triggers a live hot-reload over the loopback IPC socket:
```bash
boss plugin link
boss plugin link . --json
```

---

## Process Exit Codes & Stream Guarantees

The CLI adheres to strict UNIX process exit codes and standard stream separation:

- **Exit Code `0`**: Operation succeeded. `stdout` contains the tool output or JSON response.
- **Exit Code `1`**: Tool execution failed (`isError == true`), invalid tool arguments, or desktop app offline. Clikt usage errors also use exit code `1`. The error description is written strictly to `stderr`, leaving `stdout` clean so shell pipelines do not ingest corrupted data.
- **Output encoding**: Piped or redirected output, including every `--json` response and `boss mcp invoke` tool output, is UTF-8 on every platform; a Windows console keeps its own code page. Windows PowerShell 5.1 decodes a native command's output with `[Console]::OutputEncoding`, so set it to UTF-8 (`[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`) before capturing output that contains non-ASCII text.
- **Exit Code `2`**: `boss doctor` only. BOSS is running but reported at least one health finding. `stdout` still contains the report, so a script can branch on the code and read the details. `boss status` never uses this code.

### Offline Fail-Fast
If BossConsole is not running, commands fail immediately without hanging:
```bash
$ boss mcp list
Error: BOSS is not running. Launch BOSS to list MCP tools.
$ echo $?
1
```

---

## Security & Governance

1. **Local Authentication**: Uses a per-launch 32-byte cryptographically secure random token written to an owner-restricted runtime directory. Other OS users cannot read that token. Processes running as the same OS user can read it and are trusted by this channel.
2. **Non-Blocking Coroutines**: Tool execution runs on a background client thread with a cooperative 30-second coroutine timeout. Socket watchdogs bound client waits; a blocking plugin handler may continue after a timeout.
3. **RBAC & Kill-Switch**: All calls go through `McpToolRegistryImpl`, enforcing role-based permissions and per-tool user disable switches (`mcp-disabled-tools.json`).

PowerShell: use `--stdin` for JSON on Windows PowerShell 5.1 or legacy native argument passing, which can strip embedded quotes from `--args`. PowerShell 7.3+ uses Standard argument passing in this launcher. Packaged Windows console I/O still requires platform verification.

Registry access before sign-in follows the existing host policy: tools without required permissions or an admin requirement remain available. For an admin operator, the per-tool disabled switch is the remaining registry access control.