willys-cli

TypeScript library and CLI for the Willys grocery store API.

Search for products, browse categories, and manage your shopping cart from the terminal.

Install

npm install -g willys-cli

This installs the willys-cli command globally. Requires Node.js 18+ (for native fetch support).

Credentials

The CLI requires your Willys account credentials (personnummer + password). Provide them in one of two ways:

Environment variables (or a .env file in the working directory):

WILLYS_USERNAME=199001011234
WILLYS_PASSWORD=yourpassword

CLI flags:

willys-cli -u 199001011234 -p yourpassword 

Flags take precedence over environment variables. Quoted values in .env are stripped automatically.

CLI Usage

Searching for products

# Search for products (default 10 results)
willys-cli search mjölk

# Search with more results (auto-paginates)
willys-cli search "ekologisk mjölk" 30

Browsing categories

# List all categories (up to 3 levels deep)
willys-cli categories

# Browse products in a specific category
willys-cli browse frukt-och-gront/frukt/citrusfrukt

# Browse with pagination (page number, 0-indexed)
willys-cli browse frukt-och-gront/frukt/citrusfrukt 2

Managing your cart

# View cart contents
willys-cli cart

# Add a product (by product code, with optional quantity)
willys-cli add 101233933_ST 2

# Remove a product
willys-cli remove 101233933_ST

# Clear the entire cart
willys-cli clear

Batch operations

Create a CSV file with one operation per line (lines starting with # are ignored):

# Weekly shopping list
add,101233933_ST,2
add,101205823_ST,1
cart
remove,101205823_ST
clear

Run it:

willys-cli -i shopping-list.csv

Help

willys-cli -h
willys-cli --help

Library Usage

The package also exports a programmatic API:

import { WillysApi } from "willys-cli";

const api = new WillysApi();
await api.login("199001011234", "yourpassword");

// Search products
const results = await api.search("mjölk");
console.log(results.results[0].name);

// Manage cart
await api.addToCart([{ code: "101233933_ST", qty: 2 }]);
const cart = await api.getCart();
console.log(cart.totalPrice);

await api.logout();

API Methods

Exported Types

All response types are available as named exports:

import type { Customer, Product, SearchResult, Cart, Category } from "willys-cli";

Claude Code Integration

Install the bundled Claude Code skill into your project:

cd your-project
willys-cli --install-skills

This creates .claude/skills/willys-cli/SKILL.md, enabling Claude Code to use the Willys CLI as a tool within your project.

Development

Prerequisites

• Node.js 18+
• npm 9+

Getting started

git clone https://github.com/ErikHellman/willys-agent.git
cd willys-agent
npm install

Create a .env file with your Willys credentials:

WILLYS_USERNAME=199001011234
WILLYS_PASSWORD=yourpassword

Build & run

npm run build     # Compile TypeScript → dist/
npm start         # Run CLI in dev mode (via tsx, no build needed)
npm test          # Run integration tests (hits the live API)

Project structure

Creating a Release

1. Bump the version in package.json:

   npm version patch   # or minor / major
   

   This updates package.json and creates a git tag (e.g., v1.0.1).

2. Push the commit and tag:

   git push origin main --tags
   

3. Publish to npm:

   npm publish
   

   The prepublishOnly script runs npm run build automatically before publishing.

4. Create a GitHub release (optional but recommended):

   gh release create v1.0.1 --generate-notes
   

License

MIT - Erik Hellman