Skip to content

tomLadder/willhaben-cli

BranchesTags

Repository files navigation

🛍️ willhaben-cli

The unofficial command-line interface for willhaben.at

Manage your marketplace listings directly from the terminal. Built with TypeScript, powered by Bun.

Features • Installation • Quick Start • Commands • Configuration • Contributing

Version License Bun TypeScript Platform

Caution

Legal Disclaimer / Rechtlicher Hinweis

This is an unofficial tool and is not affiliated with willhaben.at. Using this program may violate willhaben's terms of service. You are solely responsible for ensuring your use complies with applicable terms and laws. The developers accept no liability for any damages or legal consequences arising from its use. Use at your own risk.

Dies ist ein inoffizielles Tool und steht in keiner Verbindung zu willhaben.at. Die Verwendung dieses Programms kann gegen die Nutzungsbedingungen von willhaben verstoßen. Sie sind selbst dafür verantwortlich, die Rechtmäßigkeit Ihrer Nutzung sicherzustellen. Die Entwickler übernehmen keine Haftung für Schäden oder rechtliche Konsequenzen. Die Nutzung erfolgt auf eigenes Risiko.

Features

Listing Management

  • Create listings from JSON templates
  • Update prices, titles, and descriptions
  • Reserve, unreserve, and mark items as sold
  • Republish expired listings
  • Bulk operations support

Image Support

  • Upload single or multiple images
  • View listing images
  • Delete individual or all images
  • Automatic image ordering

Authentication

  • Secure OAuth 2.0 PKCE flow
  • Automatic token refresh
  • Persistent sessions

Developer Experience

  • JSON output for scripting
  • Caching for faster responses
  • Beautiful terminal UI with spinners
  • Cross-platform compatibility

Installation

Prerequisites

  • Bun v1.0 or higher

From Source

# Clone the repository
git clone https://github.com/willhaben/willhaben-cli.git
cd willhaben-cli

# Install dependencies
bun install

# Build the standalone executable
bun run build

# Move to your PATH (optional)
mv willhaben /usr/local/bin/

Development Mode

# Run directly without building
bun run dev -- --help

Quick Start

1. Login to your account

willhaben login

A browser window will open for authentication.

2. Check your identity

willhaben whoami

3. List your active listings

willhaben list

4. Create a new listing

Create a template file my-item.json:

{
  "title": "iPhone 14 Pro - Excellent Condition",
  "description": "Selling my iPhone 14 Pro 256GB in excellent condition...",
  "price": 799,
  "postCode": "1010",
  "locationId": 900,
  "location": "Wien",
  "categoryPath": ["MOBILE_ELECTRONICS", "MOBILE_PHONES", "IPHONE"],
  "condition": "gebraucht",
  "delivery": ["PICKUP", "Versand"]
}

Then publish:

willhaben publish my-item.json

Commands

Authentication

Command Description
willhaben login Authenticate with willhaben
willhaben logout Clear stored credentials
willhaben whoami Display current user info

Listings

Command Description
willhaben list List all your listings
willhaben get <id> Get details of a listing
willhaben publish <file> Create a new listing from JSON
willhaben update <id> Update listing properties
willhaben delete <id> Delete a listing
willhaben republish <id> Republish an expired listing
willhaben deactivate <id> Take a listing offline
willhaben reserve <id> Mark as reserved
willhaben unreserve <id> Remove reservation
willhaben sold <id> Mark as sold

Images

Command Description
willhaben images <id> List images for a listing
willhaben upload-image <id> <file...> Upload one or more images
willhaben delete-image <id> <imageId> Delete a specific image
willhaben clear-images <id> Delete all images

Configuration

Command Description
willhaben config get Show all settings
willhaben config set <key> <value> Set a configuration value
willhaben config reset Reset to defaults
willhaben config path Show config file location

Command Details

List Listings

# Basic listing
willhaben list

# With pagination
willhaben list --page 2 --size 50

# Output as JSON (for scripting)
willhaben list --json

Get Listing Details

# Fetch from API
willhaben get 123456789

# Use cached data if available
willhaben get 123456789 --cached

# Output as JSON
willhaben get 123456789 --json

Update Listing

# Update price
willhaben update 123456789 --price 99.99

# Update title
willhaben update 123456789 --title "New Title"

# Update multiple fields
willhaben update 123456789 --title "New Title" --price 149

Delete Listing

# With confirmation prompt
willhaben delete 123456789

# Skip confirmation
willhaben delete 123456789 --force

Upload Images

# Upload single image
willhaben upload-image 123456789 photo.jpg

# Upload multiple images
willhaben upload-image 123456789 photo1.jpg photo2.jpg photo3.jpg

Listing Template Format

Required Fields

Field Type Description
title string Listing title (max 100 chars)
description string Detailed description
price number Price in EUR
postCode string Postal code (e.g., "8010")
locationId number Willhaben location ID
location string District/city name
categoryPath string[] Category path from root to leaf

Optional Fields

Field Type Description
street string Street address
condition string "neu", "gebraucht", or "defekt"
delivery string[] ["PICKUP"], ["Versand"], or both
attributes object Category-specific attributes
contactInfo object Contact information override
skipValidation boolean Skip attribute validation

Example Templates

Electronics - Printer 
{
  "title": "HP LaserJet Pro - wie neu",
  "description": "Verkaufe meinen HP LaserJet Pro Drucker...",
  "price": 120,
  "postCode": "8010",
  "locationId": 117458,
  "location": "Jakomini",
  "categoryPath": [
    "COMPUTER_SOFTWARE",
    "PRINTER_MONITORS_SPEAKER",
    "PRINTER",
    "LASER_PRINTER"
  ],
  "condition": "gebraucht",
  "delivery": ["PICKUP", "Versand"],
  "attributes": {
    "BRAND_PRINTER": "HP"
  }
}
Hobby - Drone 
{
  "title": "DJI Mini 3 Pro - Fly More Combo",
  "description": "DJI Mini 3 Pro mit allem Zubehör...",
  "price": 750,
  "postCode": "1010",
  "locationId": 900,
  "location": "Wien",
  "categoryPath": [
    "LEISURE_INSTRUMENTS_CULINARY",
    "MODEL_MAKING",
    "RC_MODEL_MAKING",
    "DRONES_MULTICOPTER",
    "OUTDOOR"
  ],
  "condition": "gebraucht",
  "delivery": ["PICKUP", "Versand"],
  "attributes": {
    "ENGINE_TYPE": "ELECTRIC_DRIVE"
  }
}
Books 
{
  "title": "Clean Code - Robert C. Martin",
  "description": "Buch in sehr gutem Zustand...",
  "price": 15,
  "postCode": "5020",
  "locationId": 30501,
  "location": "Salzburg",
  "categoryPath": [
    "BOOKSFILMANDMUSIC",
    "NON_FICTION_BOOKS"
  ],
  "condition": "gebraucht",
  "delivery": ["Versand"]
}

Finding Category Codes

Category codes follow the willhaben category tree structure:

Top-Level Code Category
LIVING_HOUSEHOLD_GASTRONOMY Wohnen / Haushalt
BOOKSFILMANDMUSIC Bücher / Filme / Musik
COMPUTER_SOFTWARE Computer / Software
MOBILE_ELECTRONICS Handy / Telefon
LEISURE_INSTRUMENTS_CULINARY Freizeit / Instrumente
SPORTS_LEISURE Sport / Freizeit
FASHION_ACCESSORIES Mode / Accessoires

Use willhaben categories to explore the full category tree.

Configuration

Configuration is stored in ~/.willhaben/:

File Description
config.json Settings and authentication tokens
listings.json Local listing cache

Available Settings

Key Values Default Description
outputFormat text, json text Default output format

Scripting & Automation

JSON Output

All commands support --json for machine-readable output:

# Get listing IDs
willhaben list --json | jq '.[].id'

# Check if listing exists
willhaben get 123456789 --json 2>/dev/null && echo "exists"

Batch Operations

# Reserve all listings
for id in $(willhaben list --json | jq -r '.[].id'); do
  willhaben reserve "$id"
done

# Bulk price update
willhaben list --json | jq -r '.[] | select(.price < 10) | .id' | \
  xargs -I {} willhaben update {} --price 10

Architecture

src/
├── index.ts           # CLI entry point
├── api/
│   ├── client.ts      # HTTP client with auth
│   ├── listings.ts    # Listing operations
│   ├── categories.ts  # Category tree
│   └── auth.ts        # OAuth 2.0 PKCE flow
├── cli/
│   └── commands/      # Command implementations
├── store/
│   ├── config.ts      # Configuration management
│   └── listings.ts    # Listing cache
└── types/
    └── index.ts       # TypeScript interfaces

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

Development Setup

# Clone and install
git clone https://github.com/willhaben/willhaben-cli.git
cd willhaben-cli
bun install

# Run in development mode
bun run dev -- --help

# Type checking
bun run typecheck

API Discovery

The API was reverse-engineered from the willhaben mobile app using mitmproxy. If you find new endpoints or changes:

  1. Capture traffic with mitmproxy
  2. Document the endpoint in an issue
  3. Submit a PR with the implementation

Code Style

  • Use TypeScript strict mode
  • Follow existing patterns
  • Keep functions small and focused
  • Add types for all API responses

Roadmap

  • Categories browser command
  • Bulk import from CSV
  • Watch mode for listing changes
  • Message inbox support
  • Statistics and analytics
  • Multiple account support

FAQ

How do I find my locationId?

Location IDs can be found in the category tree response or by inspecting the willhaben app traffic. Common IDs:

  • Vienna (Wien): 900
  • Graz: 117458
  • Salzburg: 30501
  • Linz: 40101
Why do I get "validation error" when publishing?

Some categories require specific attributes. Check the category's attributeReferences in the category tree, or use "skipValidation": true in your template to bypass validation (not recommended).

Can I use this for commercial purposes?

This tool is provided for personal use. Commercial use may have additional legal implications regarding willhaben's terms of service. Consult legal advice if needed.

Acknowledgments

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ in Austria

About

🛍️ Unofficial CLI for managing your willhaben.at marketplace listings from the terminal

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

Release v0.0.1 Latest
Mar 6, 2026

Packages

 
 
 

Contributors

Languages