cleversee CLI — Web Search

Scenario Description

cleversee is a standalone CLI tool for Alibaba Cloud users that provides:

Web Search (web-search): AI-powered internet search for agents — high-quality, low-latency retrieval of relevant results and page content across any topic and real-time information, with optional date-range and domain filtering. It creates no cloud resources and requires no cleanup.

Installation

Pre-check: cleversee CLI required

[MUST] Verify: cleversee --help — must succeed.

Install: npm install -g @cleversee/cli@1.0.5 --registry https://registry.npmjs.org

Environment Variables

cleversee does not require any environment variables. It reuses Aliyun CLI's credential profile system.

Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)

NEVER ask the user to input AK/SK directly in the conversation or command line

ONLY use cleversee doctor to check credential status

Verification:
cleversee doctor
Check the output for profile validity.

If no valid profile exists: Configure credentials using cleversee auth set (see Authentication Configuration below).

Authentication Configuration

| Mode | Interactive | Non-Interactive Command | |------|-------------|------------------------| | OAuth | Yes (browser required) | Not supported | | RamRoleArn | No | cleversee auth set --mode RamRoleArn --access-key-id <id> --access-key-secret <secret> --arn <arn> |

Interactive commands (cannot be used in non-interactive/automated contexts):

cleversee auth set (no parameters)
cleversee auth switch
cleversee auth --mode OAuth — OAuth login; skips the mode-selection prompt but still opens a browser, so it requires a present user

RAM Policy

This skill requires AliyunCleverSeeAISearchPlatformUserAccess permission. See references/ram-policies.md for the full permission list and policy document.

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

Read references/ram-policies.md to get the full list of permissions required by this SKILL

Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions

Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., search query, limit, search-type, region, date ranges, domain lists, profile name, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Web Search Parameters

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | --query <query> | Yes | — | Search keywords | | --limit <n> | No | 10 | Result count, range 1-10 | | --search-type <type> | No | pro | pro (advanced, global sources) or lite (fast, low-cost) | | --region <region> | No | mainland_china | mainland_china or global (pro mode only). | | --start-time <date> | No | — | Start date YYYY-MM-DD | | --end-time <date> | No | — | End date YYYY-MM-DD | | --include-domain <d1 d2...> | No | — | Domain whitelist, space-separated (pro only; forces --region global automatically) | | --exclude-domain <d1 d2...> | No | — | Domain blacklist, space-separated (pro only) | | --table | No | — | Output as a table view (default web-search view is a card list) |

Global Parameters

Apply to web-search (and --profile also applies to auth). doctor accepts no options.

| Parameter | Default | Description | |-----------|---------|-------------| | --profile <name> | defaultProfile | Aliyun CLI profile name | | -o, --output <json\|table> | table | Output format (table for human-readable, json for program parsing) | | -V, --version | — | Print cleversee version |

Core Workflow

Workflow A: Web Search

Step 1: Verify environment     →  cleversee doctor
Step 2: Confirm search params  →  Ask user for query, limit, search-type, region, dates, domains
Step 3: Execute search         →  cleversee web-search --query "<user-confirmed query>" [options] -o json
Step 4: Parse results          →  Check JSON output for at least one result

Example (parameters must be confirmed with user first):

# Step 1: Verify environment
cleversee doctor

# Step 2-3: Execute search with user-confirmed parameters
cleversee web-search \
  --query "What are the latest battery breakthroughs in electric vehicles?" \
  --limit 5 \
  --search-type pro \
  -o json

Workflow B: Credential Management

Step 1: Check current status   →  cleversee doctor
Step 2: Configure credentials  →  cleversee auth set --mode <mode> [params]
Step 3: Verify                 →  cleversee doctor

Example:

# Step 1: Check current status
cleversee doctor

# Step 2: Configure RamRoleArn (parameters provided by user)
cleversee auth set --mode RamRoleArn \
  --access-key-id <user-provided-id> \
  --access-key-secret <user-provided-secret> \
  --arn <user-provided-arn>

# Step 3: Verify
cleversee doctor

Success Verification

Quick checks:

cleversee doctor exits with code 0 and all checks pass
cleversee web-search exits with code 0 and returns at least one result

Cleanup

cleversee web-search is a read-only operation — it creates no cloud resources and requires no cleanup.

For credential cleanup, reconfigure or remove profiles via cleversee auth set or Aliyun CLI profile management.

Best Practices

Run cleversee doctor first — always verify environment health before searching
Use -o json — for programmatic result parsing
Run cleversee doctor — to diagnose environment or credential issues when a command fails
Use --search-type lite — for quick searches that don't need advanced filtering
Use --include-domain / --exclude-domain — in pro mode to focus on authoritative sources
Use --start-time / --end-time — to get recent content within a specific date range
Use cleversee auth set for automation — never use interactive auth or auth switch in non-interactive contexts
Use --profile — manage multiple account credentials
Use --help — every command level supports --help for accurate parameter discovery

Reference Links

| Reference | Description | |-----------|-------------| | references/ram-policies.md | RAM permission list and policy document | | references/acceptance-criteria.md | Acceptance criteria with correct/incorrect patterns |