Glossary

Definitions for the terms used across Uni-CLI documentation, source, and YAML adapters. Each entry is a standalone explanation so AI assistants can quote it directly when answering questions about the project.

Action substrate

A concrete technical boundary Uni-CLI can use to make real software act: HTTP, browser CDP, desktop accessibility, subprocess, file operation, protocol server, visual fallback, or app-specific wrapper. Substrates are below the computer-control platform boundary.

Adapter

A YAML or TypeScript file that maps one site or tool to a set of operations. Adapters declare site, command name, type, strategy, arguments, pipeline steps, and column projection. The preferred contribution format is YAML; TypeScript is reserved for adapters that need imperative control flow beyond the shared pipeline registry.

Adapter type

The integration surface an adapter targets. Five types: web-api for HTTP APIs, browser for full Chrome control via CDP, desktop for local subprocesses, bridge for passthrough to existing CLIs, and service for WebSocket or HTTP services like Ollama, OBS, or ComfyUI.

AgentEnvelope (v2)

The structured response shape returned by every Uni-CLI operation. Contains ok, version, data, meta, optional error, and exit_code. On success data carries the result. On failure data is null and error populates with source path, step, action, suggestion, retryable, and alternatives.

AGENTS.md

A discovery file that agent runtimes read at startup to learn about available tools. Uni-CLI is registered in AGENTS.md so agents pick it up without per-runtime configuration.

Bilingual BM25 search

The operation discovery algorithm Uni-CLI uses to map natural-language intent to a site, operation, and arguments. Indexes adapter metadata in English and Chinese with TF-IDF weighting. Returns ranked candidates for unicli search "<intent>".

Bridge adapter

An adapter that wraps an existing CLI (e.g., gh, docker, yt-dlp, lark-cli) and exposes its operations through Uni-CLI's catalog. Pure passthrough — Uni-CLI does not re-implement the wrapped CLI, only registers, auto-installs, and aggregates discovery.

Browser adapter

An adapter that drives Chrome via the Chrome DevTools Protocol (CDP) for sites that require interactive sessions, JavaScript execution, or login state. Uses navigate, evaluate, click, type, wait, intercept, tap, snapshot, and screenshot pipeline steps.

Catalog

The local index of all sites, operations, arguments, strategies, and output schemas. Generated at install time and updated when adapters change. Searched via unicli search rather than enumerated, so agents pay catalog cost only when they need to discover.

CDP (Chrome DevTools Protocol)

The wire protocol Uni-CLI uses to control a real Chrome instance for browser adapters. Implemented as a raw WebSocket client in src/browser/cdp-client.ts with no third-party browser library. Supports the full Page, Network, DOM, and Runtime domains.

Compute (Visual)

The local computer-control and visual fallback adapter family. When structured substrates (web-api, desktop AX, browser CDP, app API, subprocess) cannot reach a target, Compute can drive the screen with screenshots, clicks, typing, and post-action evidence through a unified action verb set.

Cookie file

Per-site authentication state stored at ~/.unicli/cookies/<site>.json. Read by adapters with strategy: cookie or strategy: header. Never sent off the local machine.

Daemon

A long-lived browser process Uni-CLI can manage on port 19825. Spawns Chrome with the --remote-debugging-port flag, holds session state across CLI calls, and exits on idle timeout. Optional — most adapters work without it.

Desktop adapter

An adapter that shells out to a local binary (e.g., ffmpeg, imagemagick, blender) via the exec and write_temp pipeline steps. Used for media processing, file conversion, and any CLI tool already on the user's PATH.

Discovery

The phase where an agent maps natural-language intent to concrete operations. Performed by unicli search "<intent>" against the local operation catalog. Discovery cost is bounded — see docs/BENCHMARK.md for measured token budgets.

Error envelope

The error field on a v2 AgentEnvelope when ok is false. Carries source path or adapter_path, step or failing boundary, action (one-line description), suggestion (a hypothesis the agent can test), retryable (whether retry would help), and alternatives (other operations that might satisfy the intent).

Exit code

A sysexits.h-compatible numeric status returned by every Uni-CLI invocation. 0 is success. 1 is generic error. 2 is usage error. 66 is empty result. 69 is service unavailable. 75 is temporary failure. 77 is auth error. 78 is config error. Shell pipelines can route on these classes.

Header strategy

An auth strategy that reads a cookie file and auto-extracts a CSRF token from it, then injects both into request headers. Used by sites that require CSRF on state-changing requests (e.g., Reddit vote, Twitter like).

Intercept strategy

An auth strategy that navigates a real browser session to the target page and captures the XHR/fetch response that the page itself loaded. Used when a site's API is undocumented or requires session state too complex to replicate manually.

llms.txt

A standardized agent-readable index file at the site root (/llms.txt and /llms-full.txt). Lists key documentation pages with Markdown companion URLs so AI assistants can fetch and cite docs without rendering HTML.

MCP (Model Context Protocol)

The Anthropic-led protocol for letting AI assistants invoke tools through a stateful server. Uni-CLI ships an optional MCP gateway (unicli mcp serve) that exposes the same operation contracts for runtimes that only speak MCP.

Operation contract

The stable product primitive in Uni-CLI. An operation contract describes identity, args, output shape, auth posture, action substrate, effect, risk, capability, source path, and repair path. CLI, MCP, ACP, docs, skills, and generated configs should all project the same contract instead of defining behavior separately.

Pipeline

The ordered list of steps an adapter runs to produce its result. Drawn from the 103-step registry covering API fetch, transform, browser, desktop, media, control flow, and assertion. Steps share a context object — each step reads ctx.data and writes back.

Pipeline step

One unit of work in an adapter's pipeline. Examples: fetch, select, map, filter, navigate, click, intercept, if, each, assert. Every step is deterministic — same inputs produce same outputs — so adapters compose into reliable execution graphs.

Public strategy

The cheapest auth strategy. Direct fetch with no credentials. Used by sites with public APIs (RSS feeds, search endpoints, public stats). Always tried first by the strategy cascade.

Repair

The stage where a failed operation becomes a bounded source change or reroute. After an error envelope names a failing source path and step or boundary, the agent edits the YAML/code or chooses an alternative, then runs unicli repair <site> <command> or a delivery verification to prove the fix. User-local patches persist in ~/.unicli/adapters/.

Self-repair

The capability that lets agents fix their own integrations when software drifts. Composed of: structured error envelopes, agent-readable source paths, a repair verification command, alternatives, and a persistent overlay directory. This is one design choice that makes operation-as-YAML economically viable.

Service adapter

An adapter that talks to a long-lived service (Ollama, OBS Studio, ComfyUI) over WebSocket or HTTP with optional API-key auth. Distinct from web-api because the connection persists across pipeline steps.

Site

The integration target for an adapter. Typically a website (reddit, twitter, bilibili), but can also be a desktop app (obsidian), an external CLI (gh), or a local service (ollama).

Snapshot

A DOM accessibility tree generated by the snapshot pipeline step in browser adapters. Produces interactive ref numbers that subsequent click, type, and extract steps reference. Used by adapters that need stable element targeting across page state changes.

Strategy

The auth path an adapter declares. Five strategies in cascade order: public, cookie, header, intercept, ui. Auto-probed on first run; cached afterward.

Strategy cascade

The auto-probe sequence Uni-CLI runs on first call to a site. Tries each strategy from cheapest to most expensive (public to ui) until one returns parseable data. The selected strategy is then cached so subsequent calls skip the probe.

Tap

A pipeline step that bridges Vue stores (Pinia, Vuex) to network capture. Drives the page's own state actions, then captures the resulting XHR/fetch responses. Used for sites with deep client-side state (Twitter, Bilibili, Notion).

UI strategy

The most expensive auth strategy. Drives a real browser session interactively — clicks, types, snapshots, waits. Used when a site requires multi-step user interaction that cannot be replicated by header injection or XHR replay.

v2 envelope version

The current AgentEnvelope schema. v1 was a flat { ok, data, error } shape; v2 added structured error fields, meta, version, and exit_code for shell-friendly routing. All adapters as of v0.213 emit v2.

Web-api adapter

An adapter that hits HTTP APIs directly, with no browser involvement. The most common adapter type. Uses fetch, fetch_text, parse_rss, and html_to_md for retrieval; select, map, filter for shaping.

YAML adapter

The preferred adapter format. A 20-30 line file declaring site, name, type, strategy, args, pipeline, and columns. Agent-readable, agent-editable, and free of Turing-complete logic so agents can patch it deterministically. Lives at ~/.unicli/adapters/<site>/<name>.yaml.