ZepoCli

ZepoCli gives humans and agents a clean command-line interface for shopping workflows that normally happen on Zepto:

• Search products.
• Add, inspect, remove, and clear cart items.
• List, select, and open address management.
• Open a safe checkout handoff.
• Track latest orders, view history, and reorder.
• Emit JSON for scripts and agent tooling.

It is a CLI tool, not an autonomous shopping agent. ZepoCli uses Playwright with the user's own Zepto browser session and only performs explicit user-requested actions.

Status

Current package state:

• Production CLI command surface is implemented.
• Local package verification passes.
• Production-scope live verification has accepted checkout/payment-link handoff evidence.
• Payment and order placement remain Zepto-owned and human-controlled.

Install

Requires Node.js 20.19 or newer.

npm install -g zepocli
npx playwright install chromium
zepo doctor

From this repository:

npm ci --include=prod --include=dev
npm run build
npm link
npm run prepare:browsers
zepo doctor

Quick Start

zepo --visible login
zepo status --live
zepo search milk
zepo add "Amul Milk 500ml"
zepo cart
zepo payment
zepo payment --address "home" --add "White Monster" --qr-file upi-payment.png
zepo payment --qr-file upi-payment.png
zepo track

Use JSON when another program or agent consumes output:

zepo status --live --json
zepo search milk --json
zepo add "milk" --json
zepo cart --json
zepo payment --json
zepo payment --address "home" --add "White Monster" --json
zepo cart --qr-file checkout-link.png
zepo --visible checkout --json
zepo track --json

Full usage guide: docs/USAGE.md

Command Surface

| Workflow | Commands | | --- | --- | | Session | zepo --visible login, zepo logout, zepo status, zepo status --live | | Diagnostics | zepo doctor | | Search | zepo search <query> | | Cart | zepo add <query>, zepo cart, zepo cart --qr, zepo remove <query>, zepo clear | | Payment | zepo payment, zepo payment --address <query> --add <query>, zepo payment --qr-file <path>, zepo cart --qr, zepo cart --qr-file <path>, zepo --visible checkout --qr | | Addresses | zepo address list, zepo address use <query>, zepo --visible address add | | Checkout | zepo --visible checkout, zepo --visible checkout --wait | | Orders | zepo track, zepo history, zepo reorder last | | Shells | zepo completion bash\|zsh\|fish\|powershell |

Most workflow commands support --json. Global runtime options include:

--data-dir <path>
--json
--no-input
--visible
--browser-locale <locale>
--browser-timezone <timezone>
--timeout <ms>

How It Works

CLI commands -> services -> Playwright automation -> Zepto website

ZepoCli stores local session/profile state under the configured data directory, serializes browser automation per data directory, and keeps normal installed-package commands background/headless by default.

Human-only flows require --visible:

• login
• address add
• checkout

Those commands fail early with visible_browser_required in background mode instead of opening a surprise browser.

Checkout And Payment

ZepoCli does not process payments and does not click final payment/order controls.

Live UPI payment QR in the terminal (headless, no browser window):

zepo payment
zepo payment --qr-file upi-payment.png

zepo payment reads the live cart, opens Zepto's payment choices in a background browser, selects the UPI QR option, and shows the real payment QR in your terminal. It may click Zepto's cart-side Click to Pay ₹... control only to reveal payment choices. Scan the QR with any UPI app to pay. ZepoCli does not enter payment credentials, observe payment proof, or place orders.

For fewer browser launches, combine saved-address selection, add, cart verification, and live UPI QR in one explicit command:

zepo payment --address "home" --add "White Monster" --qr-file upi-payment.png

Optional checkout-link QR (opens Zepto checkout in the user's session):

zepo cart --qr
zepo cart --qr-file checkout-link.png
zepo --visible checkout --qr
zepo --visible checkout --qr-file checkout-link.png

Checkout-link QR payload: https://www.zepto.com/?cart=open. It is not a UPI QR, payment credential, payment proof, or order proof.

Checkout browser handoff when needed:

zepo --visible checkout

After payment completes in Zepto:

zepo track

Agent Use

Agents should:

• Start with zepo doctor --json and zepo status --live --json.
• Branch on JSON error.code, not human prose.
• Treat non-zero exit codes as failure.
• Use one --data-dir per active browser session.
• Avoid parallel browser commands against the same data directory.
• Use --visible only for human-controlled Zepto flows.
• Never ask for OTPs, card numbers, CVV, UPI PIN, payment handles, or payment tokens.

See docs/USAGE.md for the full agent runbook.

Verification

Release gate:

npm run check

This runs secret scanning, dependency readiness, TypeScript build, the test suite, compiled CLI verification, installed-package verification, help smoke, audit, pack dry-run, and publish dry-run.

Live Zepto verification is manual and opt-in:

npm --silent run verify:live -- --data-dir ./.zepo-live --login --production-scope --search milk --address home --add "milk"
npm --silent run verify:live:report -- --require-production-scope --max-age-minutes 1440 ./.zepo-live/live-verification-report.json

Release

Local publish flow:

npm run check
npm publish --access public

Tag-driven release workflow:

git tag v0.1.0
git push origin v0.1.0

Never put npm tokens in the app, README, docs, tests, .npmrc, or committed config. Use NPM_TOKEN or NODE_AUTH_TOKEN only as an environment variable.

Notes

ZepoCli is an independent developer tool and is not affiliated with Zepto. Zepto owns the Zepto brand, website, checkout, payment, delivery, and order state. Use this CLI only where permitted by Zepto and applicable law.

The Zepto logo shown above is referenced from Wikimedia Commons. It may be subject to trademark restrictions.