ZepoCli

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 17 Open GitHub ↗

zepo is a terminal-first CLI for user-directed Zepto workflows.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ZepoCli

A terminal-first developer CLI for user-directed Zepto workflows.

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:

- Published npm release: `zepocli@0.1.6`.
- GitHub release tag for this package: `v0.1.6`.
- 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.

```bash
npm install -g zepocli
npx playwright install chromium
zepo doctor
```

From this repository:

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

## Quick Start

```bash
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:

```bash
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](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:

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

## How It Works

```txt
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):

```bash
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:

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

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

```bash
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:

```bash
zepo --visible checkout
```

After payment completes in Zepto:

```bash
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](docs/USAGE.md) for the full agent runbook.

## Verification

Release gate:

```bash
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. If the exact package version is already published, the publish dry-run gate skips cleanly so post-release CI can still verify the rest of the package.

Live Zepto verification is manual and opt-in:

```bash
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:

```bash
npm run check
npm publish --access public
```

Use `ZEPO_FORCE_PUBLISH_DRY_RUN=1 npm run verify:publish-dry-run` when you explicitly want to rerun npm's publish dry-run for an already-published version.

Tag-driven release workflow:

```bash
git tag v0.1.6
git push origin v0.1.6
```

The `v0.1.6` tag corresponds to the published `zepocli@0.1.6` package, including the live UPI payment QR command and one-shot payment preparation options.

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.

ZepoCli

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README