Selva

Shopping platform for AI agents. Search, compare, and buy physical products from Amazon.

User Experience

• - Be concise and human. Do not narrate command execution unless asked.
• Prefer outcome-first messaging:

- Good: "You’re registered. I can search now. Want me to find options for <item>?" - Avoid: "CLI installed... API key saved... next command is..."

• - Ask for only the missing info needed for the next step.
• When sharing links, use friendly markdown labels when supported:

- [Open settings page](https://...)

• - When listing products for chat clients, send each product as a separate message with:

- the product image as a photo attachment - a short caption (title, price, rating/reviews, delivery) - a final text message asking which item to open or buy

Default Conversation Flow

1. 1. Register quietly

- If registration is needed, do it and confirm briefly.

1. 2. Check readiness

- If name or address is missing, ask for them naturally. - If card is missing and user wants to buy, offer the settings link.

1. 3. Search and guide

- Present top choices clearly (title, price, rating, delivery/get-it-by, image url, quick reason). - Ask a simple follow-up: "Want details on any of these?"

1. 4. Buy

- Confirm selected item and payment method. - If approval flow is enabled and triggered, explain next action briefly.

Setup

1. 1. npx selva-cli register — generates an API key, stored locally at ~/selva/config.json
2. INLINECODE3 — required before buying
3. INLINECODE4 — required before buying (--line2 optional)
4. Optionally set phone: INLINECODE6
5. Optionally set email for purchase receipts and approval notifications: INLINECODE7
6. Link a payment card and optionally set an approval threshold at the web settings page: INLINECODE8

Commands

Search

npx selva-cli search "<query>" Returns up to 10 normalized results with selva_id, title, price, rating, source, url, delivery_estimate (get-it-by), and image_url. When presenting search results to users, always include delivery/get-it-by text. Prefer separate photo messages with captions (one per item) over markdown image links. Requires address for best results but works without one.

Details

npx selva-cli details <selva_id> Returns full product details from the original provider. Use the selva_id from search results (e.g. amzn_B0EXAMPLE).

Buy

npx selva-cli buy <selva_id> --method <saved|card> Requires name, address, and a chargeable card profile. Buy creates an order record and returns its current status. If an approval threshold is configured and the price exceeds it, the order enters awaiting_approval and an approval email is sent.

Options:

• - --method saved — uses the card linked on the settings page. Fails if no card is linked - ask the user to link one.
• INLINECODE19 — tokenizes with Stripe and saves a reusable payment method snapshot for later processing. Card details never reach the Selva API.

Orders

npx selva-cli orders Lists all orders with status: awaiting_approval, processing, expired, shipping. Status meaning:

• - awaiting_approval: waiting for user approval email click.
• INLINECODE22: order accepted and being processed.
• INLINECODE23: shipping status has been updated.

Settings

• - npx selva-cli settings — view current name, phone, address, email, approval threshold, and linked card info
• INLINECODE25 — generates a 24-hour link to the web settings page where a human can link/remove a payment card and set an approval threshold
• INLINECODE26
• INLINECODE27
• INLINECODE28
• INLINECODE29

Product ID Format

IDs are prefixed by provider: amzn_ for Amazon. Pass these to details and buy.

Capability Reference

• - Register user and store API key locally.
• Search products.
• Fetch product details.
• Buy by selva_id.
• View orders.
• Manage settings (name, phone, address, email, settings page link).

Command Reference

• - INLINECODE34
• INLINECODE35
• INLINECODE36
• INLINECODE37
• INLINECODE38
• INLINECODE39
• INLINECODE40
• INLINECODE41
• INLINECODE42
• INLINECODE43
• INLINECODE44