Getting Started

Uni-CLI turns websites, desktop apps, services, and local tools into commands that agents can search, run, and repair.

Install

npm install -g @zenalexa/unicli
unicli --version

Requires Node.js 20 or later.

Every command follows the same shape:

unicli SITE COMMAND [args] [-f json|md|yaml|csv|compact]

Markdown is the default output format. Use -f json when a script or other machine-oriented consumer needs JSON.

Find A Command

unicli search "hacker news frontpage"
unicli search "github trending"
unicli list --site hackernews

Run A Command

Run the selected command:

unicli hackernews top --limit 5

Use JSON when a script needs it:

unicli hackernews top --limit 5 -f json | jq '.[0]'

Supported formats:

unicli hackernews top -f md
unicli hackernews top -f json
unicli hackernews top -f yaml
unicli hackernews top -f csv
unicli hackernews top -f compact

Authentication

Some adapters need local cookies:

unicli auth setup bilibili
unicli auth check bilibili
unicli bilibili feed

Cookies live at ~/.unicli/cookies/SITE.json. Auth failures return exit code 77 and a structured error with the next command to run.

Repair A Broken Command

When a command fails, read the structured error. It includes the adapter path and pipeline step that need attention.

unicli repair SITE COMMAND

Typical loop:

1. Read error.adapter_path and error.step.
2. Patch the YAML adapter.
3. Save a local override under ~/.unicli/adapters/SITE/COMMAND.yaml.
4. Re-run unicli repair SITE COMMAND.

Browser Automation

Browser adapters use Chrome/CDP when HTTP is not enough.

unicli operate goto "https://example.com"
unicli operate snapshot
unicli operate click --ref 42
unicli operate type --ref 7 --text "hello"
unicli operate screenshot --path ./page.png

Protocol Servers

MCP:

npx @zenalexa/unicli mcp serve
npx @zenalexa/unicli mcp serve --transport streamable --port 19826

ACP:

unicli acp

ACP is an editor compatibility gateway. For coding-agent runtime routing:

unicli agents matrix
unicli agents recommend codex

Exit Codes

Code	Meaning	Agent action
0	Success	Use the data
66	Empty result	Try different parameters
69	Service unavailable	Retry later
75	Temporary failure	Retry with backoff
77	Auth required	Run unicli auth setup SITE
78	Config error	Read the error envelope and adapter YAML

Next Steps

• Adapters
• Integrations
• Self-Repair
• Pipeline Steps
• Exit Codes