volcengine/searchcli/vs-user-onboarding

vs-user-onboarding

AI Search New User Purchase Onboarding

When to Use

Use this skill when the agent detects that a user needs to complete AI Search purchase / order placement, recover from a missing-auth CLI error, configure local AK/SK, or start using SearchCLI/vs for the first time before continuing with later Viking AI Search workflows.

Common trigger phrases include:

• "I downloaded SearchCLI; how do I use it?"
• "I just installed vs; how do I get started?"
• "我下载了 SearchCLI，帮我看一下如何使用"
• "我刚装了 vs，怎么开始用"
• "我没有火山引擎账号，要怎么开始"
• "帮我接入 / 购买 Viking AI Search"

The agent must route the user to the right entry point, guide account registration and real-name verification as human checkpoints, help the user create AK/SK and configure the CLI, place the billing order through vs purchase order create after the user confirms a price quote, then query the current order status once. Order placement and status checks require local AK/SK; account registration, real-name verification, and AK/SK creation cannot be automated.

Entry Paths

Choose one entry path before running the workflow, but always start the skill by running vs auth status --json so returning users are not forced through registration again.

Credential-required commands include product and runtime commands such as vs item ..., vs search run, vs app ..., vs dataset ..., vs recommend ..., vs purchase order price, vs purchase order create, and vs purchase order status.

The CLI missing-auth recovery message is:

You are not authenticated. To get started:
- If you already have AK/SK: run `vs auth login` or `vs auth import-env`.
- If you are new to Viking AI Search: run `vs skill show vs-user-onboarding`.

Recovery routing:

• If the user already has AK/SK, guide them to vs auth login or vs auth import-env (Step 5), then check status at Step 6.
• If the user is new to Viking AI Search, continue at Step 2.
• If the user is unsure whether they purchased the product, continue at Step 2 and conservatively treat "not sure if bought" as not purchased.

Version Check

Before starting this skill workflow, run vs version check --json. Continue only when status is up-to-date. If status is update-available, stop and tell the user to update the cloned vs repository, then run git pull --ff-only, bash ./scripts/install.sh, and bash ./scripts/install-skills.sh all --target auto --force (PowerShell: scripts/install.ps1 and scripts/install-skills.ps1). If the status is unknown, stop and report that the CLI version could not be verified.

Preconditions

• The user is in the new-user registration conversion flow.
• The agent can ask the user which region/environment they use and must wait for explicit user confirmation at every human checkpoint.
• The agent places billing orders through the CLI (vs purchase order create) only after the user confirms the price quote from vs purchase order price, then calls vs purchase order status once. Account registration, real-name verification, and AK/SK creation remain human checkpoints the agent must not automate.
• vs CLI is installed. Order placement and order visibility checks require configured local AK/SK because the console OpenAPI is signed. Account registration and real-name verification happen on the console web page before AK/SK can be created.

Commands

• purchase order price: quote a purchase/renew/modify price through the console OpenAPI without creating an order; requires local AK/SK.
• purchase order create: create a billing order through the console OpenAPI; requires local AK/SK.
• purchase order status: check once whether the billing instance is visible; requires local AK/SK.
• purchase link: fallback flow that prints the console web purchase page link and does not require AK/SK; use when the user prefers the web page or a plan-eligibility error must be handled on the console.
• auth status: inspect local auth and, when AK/SK exists, classify readiness through the purchase order status path.
• doctor: inspect local CLI environment if command execution fails before reaching the service.

Workflow

Step 1: Detect current authentication state

Always run vs auth status --json first and inspect the result. In CLI versions that expose structured status, this command first checks whether local AK/SK is configured; when AK/SK exists, it uses the same backend path as vs purchase order status to verify that the Viking AI Search billing instance is visible and healthy.

• Authenticated and product enabled (status: "ok") -> run vs doctor --json; if it passes, go directly to Step 7 (early exit; do not force a returning user through registration again). A post-paid instance (including the free post-paid tier) also reports as enabled here, so do not push a post-paid user back through the purchase flow.
• `reason: "unconfigured"` -> go to Step 2; if the user already has AK/SK, Step 2 routes to Step 5.
• `reason: "invalid"` -> go to Step 5 and ask the user to reconfigure valid AK/SK.
• `reason: "product-not-enabled"` -> credentials are valid but the product is not purchased; go to Step 2. A user who already has an account and AK/SK routes as option B and proceeds to order placement (Step 6).
• `reason: "network-error"` -> ask the user to fix connectivity or endpoint configuration before continuing; do not start registration unless the user confirms they are a new buyer.

If the CLI version exposes structured failure reasons (unconfigured,

invalid, product-not-enabled, network-error), use them to skip steps

where possible (e.g., product-not-enabled with valid credentials means

registration and real-name verification are likely already done; after the

Step 2 routing confirms option B, proceed to AK/SK setup and CLI ordering).

If the CLI only reports "authenticated / not authenticated", proceed to

Step 2's question.

Step 2: Ask the user which state they are in (Stage A confirmation)

Present this exact table to the user and ask them to pick one option. Do not show the internal next-step routing to the user.

Internal routing after the user answers:

• A -> Step 3 (register and verify), then Steps 4-6
• B -> Step 4 (create AK/SK), then Steps 5-6
• C -> Step 4 (create AK/SK), then Steps 5-6
• D -> Step 5 (configure the CLI), then Step 6

Confirmation contract: the user must reply with the option letter or its plain equivalent ("A", "option A", "I don't have an account"). Free-text replies that don't clearly map to an option require re-asking. If the user is unsure ("I'm not sure if I bought it"), conservatively pick the earlier option (treat "not sure if bought" as B, not C).

Step 3 - account registration and real-name verification (entry path A only)

For users without a Volcengine/BytePlus account (option A), registration and real-name verification happen on the console web page. There is no CLI/API for them, so this is a human checkpoint and the agent must not operate the console for the user.

1. Send the user to the official console registration page matching the environment they will use (Volcano Engine for volcano-cn-beijing / volcano-ap-southeast-1, BytePlus for byteplus-ap-southeast-1).
2. Tell the user to complete real-name verification. Some plans have eligibility constraints visible only during ordering, e.g. the free trial requires an enterprise account and the first-month trial requires verification status.
3. Wait until the user explicitly confirms registration and verification are complete, then continue at Step 4.

Entry path B users (already have an account) skip this step and start at Step 4.

Step 4 - create AK/SK (entry paths A, B, and C)

Ask the user this exact question: Are you signed in as a root account or a sub-account?

• Root account: send the key management link https://console.volcengine.com/iam/keymanage, then ask the user to create or retrieve AK/SK there. Tell the user not to paste AK/SK into chat.
• Sub-account or unsure: explain that sub-accounts usually cannot create AK/SK. The user must contact the enterprise administrator, and the administrator should create and assign the access key from the key management page. Wait until the user confirms that AK/SK is available; do not attempt privilege escalation or any bypass.

This is a human checkpoint. The agent must wait for explicit confirmation that the user has AK/SK available before moving to Step 5. Entry path D users (already have AK/SK) skip to Step 5.

Step 5 - configure local credentials

Use only the supported CLI credential flows. Never ask the user to paste AK/SK into chat.

1. If VIKING_AK and VIKING_SK are already set in the user's real shell, ask the user to run vs auth import-env; otherwise, if the user has an interactive terminal, ask the user to run vs auth login.
2. During region selection, explicitly tell the user:

• Mainland China customers should choose cn-beijing.
• Southeast Asia customers, including Indonesia, Singapore, and Malaysia, should choose ap-southeast-1 (Johor).
• BytePlus customers should choose the BytePlus environment endpoints.
• The user chooses the region; the agent must not silently choose it. The region determines the billing environment and currency (CNY for China regions, USD otherwise), so it must match the account used for purchase.

1. The project defaults to default. If the user places the order under another project, pass --project-name <project-name> on the order commands and later verification commands.
2. After credentials are configured, entry paths A and B continue to Step 6 to place the order; entry paths C and D continue to Step 6 for a direct status check.

Step 6 - create order and query status

Order placement and status checks call the console OpenAPI, so they require the AK/SK configured in Step 5. Entry paths C and D skip items 1-6 and run the status check in item 7 below.

1. Before presenting the plan-selection table, query the current one-month standard-plan price:

``bash vs purchase order price \ --scene purchase \ --configuration-code ai_search_standard_monthly \ --purchase-months 1 ``

Read Result.PayableAmount and Result.Currency from the response. Use the result to render the Standard plan's one-month price in the table. Do not show a placeholder or reuse a previous quote. If the query fails, report the error and do not present a stale price.

Render the following numbered Markdown table. Translate the visible plan names and descriptions to the user's language, but keep ConfigurationCode values verbatim: