/unicli-usage

name: unicli-usage
description: >
  Command reference for Uni-CLI — the open Agent-Computer Interface runtime for
  real software.
  Use when you need to discover, run, or pipe unicli commands; or before using
  raw browser tools, legacy OpenCLI, curl, or computer-use for web, browser,
  desktop, macOS, local-tool, external-CLI, or adapter-repair tasks.

unicli Usage Guide

Quick Reference

unicli search "intent"                # Find the right command first
unicli do "goal" -f json              # Get candidates, schema, and next action
unicli describe <site> <command>      # Inspect exact args and recovery steps
unicli list                           # List all available commands
unicli list --type web-api            # Filter by adapter type
unicli list --site bilibili           # Filter by site name
unicli list --personalized            # Find signed-in user data operations
unicli search "my saved posts" --personalized

unicli upgrade --check -f json         # Compare installed and latest releases
unicli upgrade                         # Interactive Y/N choice
unicli upgrade --yes -f json           # Unattended Agent update
unicli upgrade --no -f json            # Remind again after 24 hours
unicli upgrade --no-auto-update         # Require explicit approval on this machine

unicli <site> <command> [options]     # Run any command
unicli hackernews top --limit 5       # Example: HN top stories
unicli hackernews search "AI agents"  # Example: search HN

unicli doctor                         # System health check
unicli browser doctor --json          # Browser/profile/CDP reliability report
unicli browser doctor --repair        # Start only the windowless broker
unicli browser start                  # Start hidden managed provider on demand
unicli browser --focus start          # Explicit existing-Chrome foreground control

Output Formats

Every structured envelope may include `meta.update`. Persistent non-interactive installations schedule the exact release automatically and expose progress in `meta.update.automatic_update`. Confirm the installed version before retrying a version-sensitive task. Non-interactive calls never open a prompt.

All commands support `--format` / `-f`.

| Format | Use Case | | --------- | ----------------------------------- | | `md` | Default v2 AgentEnvelope for agents | | `json` | Machine parsing / jq | | `yaml` | Config-friendly envelope | | `csv` | Spreadsheet import | | `compact` | Pipe-friendly row stream |

unicli hackernews top -f json | jq '.data[0].title'
unicli hackernews top -f csv > stories.csv

Adapter Types

| Type | Description | Example | | --------- | ------------------------ | -------------------- | | `web-api` | REST API calls | hackernews, bilibili | | `desktop` | Local desktop software | blender, gimp | | `browser` | Full browser automation | xiaohongshu | | `bridge` | Existing CLI passthrough | gh, docker | | `service` | HTTP services | ollama, comfyui |

Exit Codes

Use exit codes for scripting.

unicli hackernews top || echo "exit $?"
[ $? -eq 77 ] && echo "Login required"

| Code | Meaning | | ---- | ------------------- | | 0 | Success | | 66 | Empty result | | 69 | Service unavailable | | 77 | Auth required |

Auth and Browser Reuse

unicli browser profiles --json
unicli auth setup <site>
unicli auth import <site> --domain <domain>
unicli auth check <site>
unicli browser cookies <domain> --profile-id <id>
unicli repair <site> <command> # verifier after evidence-backed adapter edit

Browser operations are broker-owned and background-first. The default managed provider is hidden; the Chrome provider requires explicit `background` or `foreground` visibility. Doctor/status/session probes do not start the broker, browser providers, or placeholder tabs. `--focus` is the explicit foreground escape hatch.

Personalized Operations

Use the shared personalization filter for the signed-in user's feed, saved library, network, account, and activity surfaces.

unicli list --personalized
unicli list --site xiaohongshu --personalized
unicli search "my saved Xiaohongshu notes" --personalized
unicli describe xiaohongshu saved

Search and describe results expose `personalization`, `auth`, `auth_setup`, `usage`, and `inspect` where those fields apply. Execute the listed setup command before a personalized operation that requires cookies.

Chrome 136+ rejects CDP on the browser's default user-data-dir. Uni-CLI should therefore launch CDP against its own automation profile under `~/.unicli/` and reuse login state by importing cookies from `unicli browser profiles --json`. If `chrome_remote_debugging.policy.state=disabled`, the user/admin must remove `RemoteDebuggingAllowed=false` or set it true in Chrome policy, then restart Chrome; that policy does not bypass the default-profile restriction. If a browser command fails, diagnose the automation profile and cookie import path before asking the user to foreground Chrome.

Use this delivery sequence.

1. Run `unicli browser doctor --json`. 2. If `default_path.available` is true, run the requested command. 3. If false, run the first failing `checks[*].next_step`; `doctor --repair` repairs only the broker control plane. 4. Classify the remaining structured envelope. Restore auth, challenge, network, or rate-limit boundaries without editing the adapter. Only when current endpoint/DOM evidence proves selector/schema/endpoint drift, edit `adapter_path` and run `unicli repair <site> <command>` as the verifier.