Skill: mekedron/wolt-cli (version 1.0.0)

--- name: wolt-cli description: Use Nikita's local Wolt CLI to browse venues, inspect menus/items/options, and run profile, cart, and checkout-preview actions for wolt.com from terminal. Trigger when asked to find food on Wolt, inspect venue catalogs, resolve item/option IDs, automate basket or profile tasks, or debug Wolt auth/location/output behavior. --- # Wolt CLI Tool repository: https://github.com/mekedron/wolt-cli Open the repository for setup/build details, then use the local `wolt` binary: ```bash wolt <group> <command> [flags] ``` ## Session Startup 1. Inspect command tree once per session: ```bash wolt --help ``` 2. Prefer machine output for agent work: ```bash ... --format json ``` 3. Parse `.data` from the envelope and surface `.warnings`/`.error` to the user. ## Safety Rules - Start read-only by default. - Request explicit confirmation before mutating commands: - `cart add`, `cart remove`, `cart clear` - `profile favorites add`, `profile favorites remove` - `profile addresses add`, `profile addresses update`, `profile addresses remove`, `profile addresses use` - `configure` (writes local profile credentials) - Never describe `checkout preview` as order placement. The CLI does not place final orders. ## Auth Workflow Use explicit profile names to avoid ambiguity: ```bash wolt configure --profile-name default --wtoken "<token>" --wrtoken "<refresh-token>" --overwrite wolt profile status --profile default --format json --verbose ``` Credential fallback for authenticated commands: 1. Explicit flags (`--wtoken`, `--wrtoken`, `--cookie`) 2. Selected profile auth fields 3. Default profile auth fields When refresh credentials are available, expired/401 access tokens are refreshed automatically and persisted back to local config. ## Location Rules Apply exactly: - Use either `--address "<text>"` or both `--lat` + `--lon`. - Do not combine `--address` with `--lat/--lon`. - If no override is passed, profile location is used. - `search venues/items` and `venue show/hours` use `--address` or profile location (no direct `--lat/--lon` flags). - `discover`, `cart`, `checkout preview`, and `profile favorites` support `--lat/--lon`. ## Command Selection - Explore nearby options: `discover feed`, `discover categories`, `search venues`, `search items` - Inspect one venue deeply: `venue show`, `venue categories`, `venue search`, `venue menu`, `venue hours` - Resolve one item/options for basket actions: `item show`, `item options` - Basket and pricing: `cart count/show/add/remove/clear`, then `checkout preview` - Account and history: `profile show/status/orders/payments/addresses/favorites` For large marketplace venues, prefer: - `venue search <slug> --query "<text>"` - `venue menu <slug> --category <category-slug>` instead of unrestricted full-catalog menu crawl. ## Output and Diagnostics - `--format json|yaml` returns envelope keys: `meta`, `data`, `warnings`, optional `error`. - On upstream failures, rerun with `--verbose` to capture request trace and detailed diagnostics. ## References - Full command and flag matrix: `references/command-reference.md` - Reusable high-confidence workflows: `references/workflows.md` - Envelope/error parsing and automation notes: `references/output-and-errors.md`

path: references/workflows.md
content: # Workflows

## 1) Authenticate and Validate Session

```bash
wolt configure --profile-name default --wtoken "<token>" --wrtoken "<refresh-token>" --overwrite
wolt profile status --profile default --format json --verbose
wolt profile show --profile default --format json
```

If status fails with upstream/auth errors, keep `--verbose` and surface exact error code/message.

## 2) Find Venue, Inspect Item, Add to Cart, Preview Checkout

```bash
# Discover/search
wolt search venues --profile default --query "burger" --limit 10 --format json
wolt venue show <venue-slug> --profile default --format json

# Resolve item and options
wolt venue search <venue-slug> --query "whopper" --include-options --limit 10 --profile default --format json
wolt item options <venue-slug> <item-id> --profile default --format json

# Mutation (confirm with user first)
wolt cart add <venue-id> <item-id> --venue-slug <venue-slug> --option "<group-id>=<value-id>" --profile default --format json

# Validate basket and pricing preview
wolt cart show --venue-id <venue-id> --details --profile default --format json
wolt checkout preview --venue-id <venue-id> --delivery-mode standard --profile default --format json
```

## 3) Large Marketplace Venue Strategy (Partial Assortments)

Use this path when `venue menu` is incomplete or returns partial-assortment guidance:

```bash
wolt venue categories <venue-slug> --profile default --format json
wolt venue search <venue-slug> --query "milk" --profile default --format json
wolt venue menu <venue-slug> --category <category-slug> --include-options --profile default --format json
```

Use `--full-catalog` only when explicitly needed; it can be slow.

## 4) Orders and Payment/Profile Inspection

```bash
wolt profile orders --profile default --limit 20 --format json
wolt profile orders show <purchase-id> --profile default --format json
wolt profile payments --profile default --mask-sensitive --format json
wolt profile favorites --profile default --format json
```

## 5) Address Book Operations (Mutating)

Confirm intent before add/update/remove/use.

```bash
wolt profile addresses --profile default --format json
wolt profile addresses add --profile default --address "<formatted>" --lat <lat> --lon <lon> --label home --format json
wolt profile addresses links --profile default --format json
wolt profile addresses use <address-id> --profile default --format json
```

## 6) Location Override Rules

- Valid: `--address "Kamppi, Helsinki"`
- Valid: `--lat 60.1699 --lon 24.9384`
- Invalid: `--address ... --lat ... --lon ...` together
- Invalid: only one coordinate flag

On invalid combinations, expect `WOLT_INVALID_ARGUMENT`.


path: references/command-reference.md
content: # Command Reference

## Invocation

Tool repository: https://github.com/mekedron/wolt-cli

Open the repository for setup/build details, then use the local binary:

```bash
wolt <group> <command> [flags]
```

Leaf commands share global flags unless noted:

- `--format table|json|yaml`
- `--profile <name>`
- `--address "<text>"`
- `--locale <bcp47>`
- `--no-color`
- `--wtoken <token>`
- `--wrtoken <refresh-token>`
- `--cookie <name=value>` (repeatable)
- `--verbose`

`configure` uses its own flags and writes local profile auth config.

## Root Groups

- `auth`
- `cart`
- `checkout`
- `configure`
- `discover`
- `item`
- `profile`
- `search`
- `venue`

## Configure

- `wolt configure --profile-name <name> [--wtoken ...] [--wrtoken ...] [--cookie ...] [--overwrite]`
- Default profile-name is `Default`; pass explicit `--profile-name default` for consistency.

## Auth

- `wolt auth status`
- Equivalent auth probe: `wolt profile status`

## Discover

- `wolt discover feed [--limit <n>] [--wolt-plus] [--address ... | --lat ... --lon ...]`
- `wolt discover categories [--address ... | --lat ... --lon ...]`

## Search

- `wolt search venues [--query <text>] [--sort ...] [--type ...] [--category ...] [--open-now] [--wolt-plus] [--limit <n>] [--offset <n>]`
- `wolt search items --query <text> [--sort ...] [--category ...] [--limit <n>] [--offset <n>]`

## Venue

- `wolt venue show <slug> [--include hours,tags,rating,fees] [--address ...]`
- `wolt venue categories <slug>`
- `wolt venue search <slug> --query <text> [--category <slug>] [--include-options] [--limit <n>]`
- `wolt venue menu <slug> [--category <slug>] [--full-catalog] [--include-options] [--limit <n>]`
- `wolt venue hours <slug> [--timezone <iana>] [--address ...]`

## Item

- `wolt item show <venue-slug> <item-id> [--include-upsell]`
- `wolt item options <venue-slug> <item-id>`

`item options` returns `example_option` values in `group-id=value-id` format suitable for `cart add --option`.

## Cart

- `wolt cart count`
- `wolt cart show [--venue-id <id>] [--details] [--address ... | --lat ... --lon ...]`
- `wolt cart add <venue-id> <item-id> [--count <n>] [--option <group-id=value-id[:count]> ...] [--allow-substitutions] [--name ...] [--price ...] [--currency ...] [--venue-slug <slug>] [--lat ... --lon ...]`
- `wolt cart remove <item-id> [--count <n>] [--all] [--venue-id <id>] [--address ... | --lat ... --lon ...]`
- `wolt cart clear [--venue-id <id>] [--all] [--address ... | --lat ... --lon ...]`

If multiple baskets exist and no `--venue-id` is passed, commands select the first basket.

## Checkout

- `wolt checkout preview [--delivery-mode standard|priority|schedule] [--tip <minor-units>] [--promo-code <id>] [--venue-id <id>] [--address ... | --lat ... --lon ...]`

Preview only. No final order placement.

## Profile

- `wolt profile show [--include personal,settings]`
- `wolt profile status`
- `wolt profile orders [--limit 1-50] [--page-token <token>] [--status <value>]`
- `wolt profile orders list [--limit 1-50] [--page-token <token>] [--status <value>]`
- `wolt profile orders show <purchase-id>`
- `wolt profile payments [--label <contains>] [--mask-sensitive]`
- `wolt profile addresses [--active-only]`
- `wolt profile addresses add --address ... --lat ... --lon ... [--type ...] [--label ...] [--alias ...] [--detail key=value ...] [--set-default-profile]`
- `wolt profile addresses update <address-id> --address ... --lat ... --lon ... [--type ...] [--label ...] [--alias ...] [--detail key=value ...] [--set-default-profile]`
- `wolt profile addresses remove <address-id>`
- `wolt profile addresses use <address-id>`
- `wolt profile addresses links [address-id]`
- `wolt profile favorites [--address ... | --lat ... --lon ...]`
- `wolt profile favorites list [--address ... | --lat ... --lon ...]`
- `wolt profile favorites add <venue-id-or-slug>`
- `wolt profile favorites remove <venue-id-or-slug>`

Aliases:

- `wolt profile favorites` alias: `favourites`
- `wolt profile orders` aliases: `history`, `order-history`


path: references/output-and-errors.md
content: # Output and Errors

## Machine-Readable Envelope

Use `--format json` for automation. Every response follows:

```json
{
  "meta": {
    "request_id": "req_xxx",
    "generated_at": "2026-02-19T20:45:09Z",
    "profile": "default",
    "locale": "en-FI"
  },
  "data": {},
  "warnings": [],
  "error": {
    "code": "WOLT_AUTH_REQUIRED",
    "message": "...",
    "details": {}
  }
}
```

`error` is omitted on success.

## Parsing Guidelines

- Read primary payload from `.data`.
- Always inspect `.warnings` and surface important warnings.
- On failure, present `.error.code` and `.error.message`.
- Keep `meta.request_id` for troubleshooting/log correlation.

## Common Error Codes

- `WOLT_AUTH_REQUIRED`: missing credentials
- `WOLT_INVALID_ARGUMENT`: invalid flag combinations or required args missing
- `WOLT_PROFILE_ERROR`: profile load/select/write failure
- `WOLT_LOCATION_RESOLVE_ERROR`: address geocoding failure
- `WOLT_UPSTREAM_ERROR`: upstream HTTP/API failure (details with `--verbose`)
- `WOLT_EMPTY_CART`: checkout/cart mutation attempted without basket items
- `WOLT_ITEM_NOT_FOUND`: item not found in selected basket/venue
- `WOLT_REMOVE_UNSUPPORTED`: remove operation cannot be mapped safely
- `WOLT_CHECKOUT_PAYLOAD_ERROR`: failed to build checkout preview payload
- `WOLT_NOT_FOUND`: requested address/entity missing

## Diagnostics

Rerun with `--verbose` when debugging:

- enables HTTP trace output to stderr
- preserves machine envelope in stdout
- returns richer upstream error details

## Exit Codes

- `0`: success
- `1`: command/domain/upstream error
- `2`: unknown command


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)