---
slug: "uni-cli"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/olo-dot-io/uni-cli@main/README.md"
repo: "https://github.com/olo-dot-io/uni-cli"
source_file: "README.md"
branch: "main"
---
Uni-CLI
English · 简体中文
The open Agent-Computer Interface runtime for real software.
One searchable boundary between agents and websites, logged-in browsers,
desktop apps, local tools, files, operating-system services, and agent
protocols. Uni-CLI ranks cataloged operations by intent, runs the selected
operation through its declared software substrate under policy, wraps the
result in a stable success/error envelope, and keeps failure diagnosable and
repairable.
Docs
·
Operation catalog
·
Agent index
Native CLI · MCP · ACP · JSON/Markdown envelopes · browser CDP · visual fallback · macOS desktop AX · 324 static adapter surfaces · 9816 tests
Find the operation. Cross the boundary. Keep the outcome inspectable.
Discover → select → govern → act → observe → repair.
## Install And Run In 30 Seconds
```bash
npm install -g @zenalexa/unicli
unicli do "find the Hacker News frontpage"
unicli extract https://example.com --max-chars 1200
unicli compute snapshot --app Calculator --format compact
npx @zenalexa/unicli mcp serve
```
| The agent needs to know... | Uni-CLI answer |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| What can act on this task? | `unicli search` and plan-only `unicli do` retrieve a small ranked set; the agent explicitly invokes one result |
| Which boundary will act? | Each operation declares its strategy and substrate: API, file, CLI, browser, desktop, protocol, or visual |
| What will the action affect? | Operation contracts expose arguments, auth, capability scope, effect, risk, and approval posture |
| What did the call return? | AgentEnvelope always distinguishes success from error; supporting operations add artifacts, recordings, or post-state evidence |
| The path drifted—what now? | Structured errors can name the owned source, failed step, retryability, alternatives, and next repair command |
| How does my agent call it? | Native CLI is canonical; MCP projects adapter operations through default, deferred, or expanded profiles |
## Why It Exists
Models are only half of an agent system. The other half is the interface they
use to perceive state, choose actions, cross software boundaries, and interpret
feedback. Human interfaces are optimized for eyes, hands, and memory. Raw APIs
and giant tool lists are optimized for developers or protocols. Neither is a
complete interface for a model with a bounded context window and a task to
finish.
Uni-CLI owns that missing boundary: the **Agent-Computer Interface (ACI)**. It
does not choose the model or orchestrate the agent's reasoning. It makes real
software discoverable and operable, then returns structured results the agent
can inspect. Evidence-capable operations can additionally record artifacts,
state deltas, or trajectories. Browser automation, app harnesses, MCP,
WebMCP, accessibility, subprocesses, and visual control remain replaceable
substrates below the interface.
## The Agent-Computer Interface Loop
The six verbs are the compact product story. The executable architecture stays
more explicit: `unicli architecture audit` reports nine runtime stages —
`intent`, `select`, `govern`, `act`, `observe`, `diagnose`,
`repair-or-reroute`, `deliver`, and `expose`.
| Product concern | Current runtime truth |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Discover | `search` and plan-only `do` rank candidate operations from intent; neither command performs the external action |
| Select | the agent or caller selects an operation whose contract declares a strategy and substrate; Uni-CLI does not yet arbitrate all alternatives |
| Govern | `open`, `confirm`, and `locked` profiles evaluate supported operation effects and capability scopes |
| Act | adapter commands run through the shared adapter kernel; fixed core commands keep their own native CLI handlers |
| Observe | every rendered call has a stable success/error envelope; operation-specific evidence is optional and never inferred from dispatch alone |
| Repair | structured errors and delivery tools can bound a diagnosis, reroute, or verification attempt where the operation supplies that context |
`diagnose` and `deliver` make observation actionable; `expose` projects the
runtime into agent-facing entry points. Adapter operations are shared by native
CLI and the MCP profiles. Fixed core commands are currently canonical on the
native CLI; command-by-command protocol parity is an explicit roadmap item.
## What Makes It Different
| If you start from... | It is excellent at... | Uni-CLI's distinct boundary |
| ------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| App/site-to-CLI harnesses | creating a deep structured interface for one surface | discovering and running many interfaces through one catalog and structured failure model |
| Browser agents or browser MCP | perceiving, planning, and acting inside a browser | using browser control as one substrate without becoming the model or planner |
| Hosted SaaS integration platforms | managed OAuth, users, triggers, and cloud toolkits | open, local-first access to the user's actual browser, desktop, files, and local tools |
| MCP registries and operations systems | cataloging, running, proxying, or governing MCP servers | exposing adapter operations while also reaching non-MCP software through native commands |
| Discovery standards such as ARD | publishing where capabilities exist | checking a local executable path, invoking it, reporting its result, and repairing drift |
Uni-CLI is not an agent framework, model runtime, hosted integration
marketplace, enterprise MCP gateway, or operating system. It is the interface
runtime those systems can call when an agent needs to use real software.
## What It Controls
Uni-CLI treats the computer as the environment and each controllable boundary as
a substrate. The substrate can be high-level and typed, or low-level and visual;
the receipt remains the same.
| Layer | What it controls |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operation contracts | reusable actions with args, output shape, auth posture, safety metadata, source path, and repair path |
| Web and APIs | public, cookie, header, browser-intercept, download, upload, publish, extract, and search workflows |
| Browser sessions | CDP navigate/click/type/fill/select/wait/network/screenshot/snapshot/evidence |
| Desktop and OS | macOS apps, Accessibility refs, screenshots, clipboard, calendar, brightness, app actions, and local system state |
| Local tools/files | subprocess bridges, external binaries, PDF and paper workflows, file transforms, media tools, and developer CLIs |
| Agent protocols | native CLI, JSON stream, MCP, ACP, Streamable HTTP, OpenAI-compatible routes, generated configs, and skills |
| Policy and evidence | permission profiles, deny rules, approvals, run recording, replay, probe, compare, browser session leases, render-aware evidence, movement checks, and stale-ref details |
| Delivery and repair | `unicli delivery assess`, `run`, `trajectory`, and `repair-candidate` for objective-level evidence gates, diagnoses, hypotheses, executed attempts, reroutes, and bounded repairs |
## Built For Agent Runtimes
Uni-CLI is intentionally boring at the boundary. It speaks processes, files,
JSON, Markdown, and standard protocols. That makes it usable from agent
runtimes, shell scripts, CI, and any host that can spawn a subprocess or attach
an MCP server.
The runtime is agent-friendly in ways that matter during long tasks:
- commands are discoverable by intent, not by memorizing names;
- outputs are stable enough to pipe to `jq`, save as evidence, or feed back into
another tool call;
- auth failures, empty results, timeouts, and blocked actions are distinct exit
states;
- repair instructions point to the owned file instead of asking the agent to
guess what changed upstream;
- generated docs, `llms.txt`, AGENTS.md, and skills describe the catalog;
MCP profiles project adapter operations, while fixed-core parity remains
roadmap work.
## Capability Map
| Layer | Examples |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| Intent and discovery | `search`, `do`, generated operation catalog, docs index, compact catalog, AGENTS surface |
| Operation contract | args, output, auth posture, effect, safety, capability, source path, repair path |
| Action substrates | HTTP, RSS, CDP, AX/UIA/AT-SPI, subprocess, visual, protocol, app-specific adapters |
| Local computer control | `compute apps`, `snapshot`, `find`, `click`, `type`, `press`, `scroll`, `doctor compute` |
| Policy and evidence | permission profiles, deny rules, approvals, run recording, replay, probe, compare |
| Delivery and repair | objective specs, trajectories, repair candidates, reroutes, evidence gates |
| Runtime exposure | native CLI, MCP stdio, MCP Streamable HTTP, ACP, package exports, agent skills |
## For Agents
Use search first, then run the smallest matching command.
```bash
unicli search "connect slack messages" --limit 5
unicli slack search "deploy incident" -f json
unicli anilist characters "Sparkle" --limit 5 -f json
unicli danbooru tags sparkle --limit 5 -f json
unicli arxiv download 1706.03762 --output ./papers -f json
unicli pdf read ./papers/1706.03762.pdf --first_page 1 --last_page 3 -f json
unicli macos app-actions --app WhatsApp -f json
unicli macos automation-smoke -f json
unicli repair slack search
```
Output defaults to structured Markdown for non-TTY and agent-user-agent runs. Force a machine format when you need one:
```bash
UNICLI_OUTPUT=json unicli reddit hot --limit 10
unicli hackernews top --limit 5 -f yaml
unicli --record --permission-profile confirm twitter search "coding agents" -f json
unicli runs list -f json
unicli runs show -f json
unicli runs probe -f json
unicli runs replay --permission-profile confirm --yes --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
unicli runs compare -f json
unicli runs compare --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
unicli --permission-profile locked --yes --remember-approval word set-font "Inter"
unicli approvals list -f json
unicli approvals revoke -f json
unicli browser evidence --render-aware --expect-domain example.com -f json
```
Protocol entry points:
```bash
npx @zenalexa/unicli mcp serve
npx @zenalexa/unicli mcp serve --transport streamable --port 19826
unicli acp
unicli agents recommend codex
unicli agents matrix
```
ACP is supported for editors and bridge tooling. The primary runtime path stays native CLI, JSON stream, or MCP when those routes are available.
## Local Computer Control
`unicli compute` controls installed apps through native accessibility, Electron CDP, and visual fallback transports.
```bash
unicli compute apps
unicli compute snapshot --app Calculator --format compact
unicli compute find --role button --name 5 --first
unicli compute find --role input --text 8 --first
unicli compute click @e7
unicli doctor compute --json
npx @zenalexa/unicli mcp serve --profile computer-use
```
Start with [Compute](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/operate/compute.md), [Electron App Control](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/operate/electron.md), and [Compute Troubleshooting](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/operate/troubleshooting.md).
## Coverage
The catalog is intentionally broad. Catalog rows are discoverable and typed;
that is inventory evidence, not proof that a third-party endpoint or login is
healthy today. Fixture shape, live endpoint health, and authenticated-browser
health are tracked as separate evidence layers and never added together as one
"working commands" claim. Recent inventory includes scholarly paper
download/read workflows, ACG/anime/manga/wiki discovery, booru tag search,
visual-novel catalogs, and Japanese/romaji-aware entity lookup.
The wall below is generated from active manifest sites with real logo support. Badge counts exclude quarantined commands. The full generated catalog stays in `unicli list` and the docs site.
See the live catalog:
```bash
unicli list
unicli list --site macos
unicli ext list
unicli ext list --tag agent
```
Browse the same generated catalog on the docs site:
## Output Contract
Every normal command returns a v2 envelope. `mcp serve` and `acp` are protocol servers and keep their raw stdio protocol.
```yaml
ok: true
schema_version: "2"
command: "twitter.search"
meta:
duration_ms: 412
count: 20
surface: web
data:
- { id: "...", text: "...", author: "..." }
error: null
```
Errors are meant to be acted on:
```yaml
ok: false
schema_version: "2"
command: "twitter.search"
meta:
duration_ms: 91
data: null
error:
code: auth_required
message: "401 Unauthorized"
adapter_path: "src/adapters/twitter/search.yaml"
step: 1
suggestion: "Run: unicli auth setup twitter"
retryable: false
alternatives: ["twitter.timeline", "twitter.profile"]
```
Exit codes: `0` ok, `66` empty, `69` unavailable, `75` temporary failure, `77` auth, `78` config.
## Self-Repair
Adapters are small YAML files by default. A failed command gives an agent enough context to patch the broken part without waiting for a package release.
```text
1. Run the command.
2. Read the error envelope.
3. Open error.adapter_path.
4. Patch the failing step.
5. Save the override in ~/.unicli/adapters//.yaml.
6. Verify once with unicli repair .
7. Inspect representative rows from the original command.
```
`unicli repair` never edits source or git state. It re-runs the original command
as a bounded subprocess and succeeds only when the target envelope is `ok=true`
and its process exits `0`; failures preserve the target error and exit code.
Local overrides survive npm updates. See [Self-Repair](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/guide/self-repair.md).
## Write An Adapter
```yaml
site: example
name: search
description: "Search example.com"
transport: http
strategy: public
capabilities: [fetch, select, map, limit]
minimum_capability: http.fetch
trust: public
confidentiality: public
quarantine: false
pipeline:
- fetch:
url: "https://api.example.com/search?q=${{ args.query }}"
- select: data.results
- map:
title: "${{ item.title }}"
url: "${{ item.url }}"
- limit: "${{ args.limit }}"
args:
- { name: query, type: string, required: true, positional: true }
- { name: limit, type: int, default: 20 }
columns: [title, url]
```
Docs:
- [Documentation site](https://olo-dot-io.github.io/Uni-CLI/)
- [Getting started](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/guide/getting-started.md)
- [Integrations](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/guide/integrations.md)
- [Adapter format](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/ADAPTER-FORMAT.md)
- [Pipeline reference](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/reference/pipeline.md)
- [Exit codes](https://github.com/olo-dot-io/uni-cli/blob/HEAD/docs/reference/exit-codes.md)
## Trust And Limits
- Auth-required commands can read a live local browser/CDP session into memory.
They do not persist it by default. `unicli auth import` and
`unicli browser cookies` are explicit plaintext-JSON persistence paths under
`~/.unicli/cookies/.json` (POSIX: directory `0700`, file `0600`).
- Browser adapters use one owner-only Browser Runtime Broker. The default
managed provider is hidden and uses Uni-CLI automation profiles under
`~/.unicli/`; Agent sessions own distinct targets while declared profile
partitions can share login/storage. Existing Chrome requires the native
host and explicit background or foreground visibility. Install it with
`unicli browser native-host install --browser chrome`, then use
`unicli browser native-host extension-path` to locate the unpacked extension.
Empty profiles
require explicit `unicli browser start --ephemeral` or
`UNICLI_BROWSER_EPHEMERAL=1`.
Chrome 136+ blocks remote debugging on the default user-data-dir.
`RemoteDebuggingAllowed` policy can disable remote debugging entirely, but it
cannot make default profile CDP supported again.
- `unicli browser doctor --json` reports `default_path`, per-check
`next_step` commands, `profile_source`, `chrome_remote_debugging`, and
broker/provider/session/lease evidence. `unicli browser doctor --repair`
starts only the windowless broker and never starts a browser provider.
- Permission profiles are user-selected runtime policy. The default is `open`;
stricter `confirm` and `locked` profiles require `--yes` or `UNICLI_APPROVE=1`
for blocked operations. Add `--remember-approval` with `--yes` to store the
same command capability and resource scope under `~/.unicli/approvals.jsonl`.
Resource scope covers stable metadata such as domain, account surface, app,
process family, and path argument slots. Use
`unicli approvals list`, `revoke`, and `clear` to inspect or remove remembered
scopes. The file stores scope metadata; runtime args stay out of approval
memory.
- Local JSON or YAML rules live at `~/.unicli/permission-rules.json`, or at
`UNICLI_PERMISSION_RULES_PATH`. Schema v1 remains deny-only. Schema v2 adds
deny-first `allow`/`deny` rules, an explicit `default`, and bounded argument
constraints (`min`, `max`, `max_length`, RE2 `pattern`, `allowed`). Rules can
also match site, command, effect, capability dimensions, and resource
metadata. Direct `browser`/`operate`, `compute`, and computer-use MCP calls
authorize before broker, transport, overlay, file, clipboard, or desktop
side effects. Denials outrank `--yes` and remembered approvals. An explicit
missing or malformed policy fails closed; the absent implicit default file
leaves policy disabled. Pipeline runtime guards additionally check fetched
domains, navigation targets, download/output paths, and subprocess
executables at their resolved boundary.
- Run recording is opt-in. Use `--record` or `UNICLI_RECORD_RUN=1` when you need
append-only evidence under `~/.unicli/runs`.
- Privacy-safe invocation diagnostics are recorded by default as 30-day,
owner-only UTC JSONL files under `~/.unicli/logs/events`; arguments, content,
URLs, credentials, and raw errors are excluded. Inspect aggregates with
`unicli usage report -f json`, configure retention with
`UNICLI_LOG_RETENTION_DAYS`, or disable new events with `UNICLI_NO_LOG=1`.
- Visual fallback routes require a configured real backend. Declared-but-unavailable providers fail closed with structured errors.
- User adapters and repairs live in `~/.unicli/adapters/`; committed adapters remain the package baseline.
- If a site blocks automation or changes a private API, Uni-CLI returns a clear failure envelope.
## Development
```bash
npm install
npm run typecheck
npm run lint
npm run verify
```
## License
[Apache-2.0](https://github.com/olo-dot-io/uni-cli/tree/HEAD/LICENSE)
v0.400.2 — Apollo · Duke
