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

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:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. 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

Global Parameters

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

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

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

Reference Links