takealot

name	takealot
description	Shop on Takealot.com from the terminal. Search, add to cart, and checkout via pure API.

takealot skill

Shop on Takealot.com from the terminal — search products, manage your cart, check out, and review order history. Talks directly to the Takealot mobile REST API; no browser required.

Install

brew install yashiels/tap/takealot

Or download a standalone binary from the latest release.

Build from source (Node ≥ 18 required):

git clone https://github.com/yashiels/takealot-cli.git
cd takealot-cli
npm install && npm run build
npm link   # puts `takealot` on your PATH

Credentials

Credentials are managed by the takealot login command and cached automatically. The CLI stores email, plaintext password (protected only by filesystem permissions, chmod 0600), and cached tokens in ~/.config/takealot-cli/credentials.json (XDG-respecting, chmod 0600).

The login command prompts for your Takealot account email and password interactively, then caches the token set. If your account has two-step verification (2FA) enabled, you will also be prompted for an OTP code sent to your phone. Tokens auto-refresh on expiry; if refresh fails and full login is required, a 2FA account requires an interactive OTP prompt.

Automated / agent usage

First-time login requires an interactive terminal:

• If your account has 2FA enabled, you'll be prompted for an OTP code sent to your phone. Token refresh works without interaction; full re-login on a 2FA account requires an interactive OTP prompt.
• Seed credentials once, interactively, on the machine: run takealot login in a real terminal so ~/.config/takealot-cli/credentials.json gets populated. After that, most calls work without interaction via token refresh.
• Never run takealot login --reset unattended. It re-prompts for email/password and throws --reset needs an interactive terminal when there is no TTY. If credentials are wrong, ask the user to run takealot login --reset themselves.
• If no credentials are cached yet, any authed command fails with No saved credentials. Run 'takealot login' in an interactive terminal first. — surface that to the user rather than retrying; an agent cannot complete first-time login unattended.
• Search needs no login, so takealot search … --json always works.
• For checkout, always dry-run first (takealot checkout) and only pass --confirm --yes when the user has explicitly approved the order and total.

Commands

Search (no login required)

takealot search <query>
takealot search <query> --limit <n>     # max results (default 10)
takealot search <query> --json          # machine-readable output

Examples:

takealot search "protein powder"
takealot search "pencils" --limit 5
takealot search "coffee" --json | jq '.[0]'

Cart

takealot cart                           # show current cart
takealot cart add <item>                # add one item (preference-ranked match)
takealot cart basket "<item>; ..."      # add several items at once
takealot cart clear                     # empty the cart

cart add accepts an optional leading quantity:

takealot cart add "3 pencils"
takealot cart add "2 packs sunscreen"

cart basket splits on commas, semicolons, or newlines and adds items in parallel:

takealot cart basket "milk; bread; eggs; coffee"
takealot cart basket "3 pens, notebook, sticky notes"

Checkout

takealot checkout                       # dry-run: print totals, address, card — no charge
takealot checkout --confirm             # place the order and pay with the saved card
takealot checkout --confirm --yes       # skip the interactive confirmation prompt

The dry-run prints the full order summary (items, delivery address, payment method, total) so you can verify before committing.

Orders

takealot orders                         # list recent orders (default 20)
takealot orders --limit <n>             # show more/fewer orders
takealot orders show <id>               # full detail for one order

Preferences

The preference engine learns from your order history and ranks search results for cart add.

takealot preferences                    # show the current preference cache
takealot preferences show               # same
takealot preferences refresh            # rebuild cache from full order history

Run preferences refresh after your first login to seed the cache.

Config

takealot config                         # show config and credential status (secrets redacted)
takealot config show                    # same

Config lives in ~/.config/takealot-cli/ (respects $XDG_CONFIG_HOME):

File	Contents
config.json	API base URLs, preferred card, explicit brand list
credentials.json	Email, plaintext password (protected only by filesystem permissions, chmod 0600), and cached tokens
preferences.json	Order-history preference cache

Auth

takealot login                          # log in, cache tokens
takealot login --reset                  # clear stored credentials and re-authenticate

Global Flags

Flag	Effect
--json	Machine-readable JSON output (works on every command)
--verbose	Print debug logging to stderr
--version	Print the version and exit
--help	Show help for any command or subcommand

Exit codes: 0 success · 1 general failure

Preference Engine

When you run takealot cart add, the tool picks the best product match through a ranked funnel:

1. Exact match — a product you've ordered before with the same title
2. Brand match — a product in the same category from a brand you've bought before
3. Explicit brand list — brands listed in config.json → preferredBrands
4. Fuzzy similarity — Jaccard coefficient on title tokens

Seed the cache once with takealot preferences refresh after your first login. The cache updates automatically as you order more.

Quick-Start Example

# 1. Install
brew install yashiels/tap/takealot

# 2. Authenticate
takealot login

# 3. Seed the preference engine
takealot preferences refresh

# 4. Search and shop
takealot search "protein bar" --limit 5
takealot cart add "2 protein bars"
takealot cart basket "milk; bread; eggs"
takealot cart

# 5. Review and place order
takealot checkout              # dry-run first
takealot checkout --confirm    # then pay