vinted-cli 0.1.0__tar.gz

vinted_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Check distributions
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

vinted_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+*.egg

vinted_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paatsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vinted_cli-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: vinted-cli
+Version: 0.1.0
+Summary: Fast CLI for searching Vinted — optimized for agents and scripting
+Project-URL: Homepage, https://github.com/Paatsu/vinted-cli
+Project-URL: Repository, https://github.com/Paatsu/vinted-cli
+Project-URL: Issues, https://github.com/Paatsu/vinted-cli/issues
+Author: Paatsu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,fashion,marketplace,search,sweden,vinted
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vinted-cli
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Fast CLI for searching [Vinted](https://www.vinted.se).
+
+Primary target is vinted.se but can be configured to work with any Vinted country. Designed for agents, scripts, and quick terminal lookups. Minimal dependencies, structured output.
+
+## Install
+
+**From PyPI:**
+
+```bash
+pip install vinted-cli
+```
+
+**Upgrade:**
+
+```bash
+pip install --upgrade vinted-cli
+```
+
+## Usage
+
+### Search listings
+
+```bash
+vinted search "jeans"
+vinted search "iphone 15" --price-max 5000
+vinted search "nike" --condition very-good --sort price-asc
+vinted search "dress M" --sort newest -n 10
+vinted search "jacka" -o json | jq '.results[:3]'
+vinted search --catalog-id 1231          # browse a category without a query
+vinted search --price-max 100 --sort newest  # all cheap new listings
+```
+
+### Get item details
+
+```bash
+vinted item 1234567890
+vinted item 1234567890 -o json
+vinted item 1234567890 --country fr
+```
+
+### Browse filters
+
+```bash
+vinted countries                   # list all supported country codes
+vinted conditions                  # list item condition filters
+vinted catalogs                    # list the full catalog tree
+vinted catalogs --parent-id 2994   # list subcatalogs of Electronics
+```
+
+## Output formats
+
+| Flag | Format | Use case |
+|------|--------|----------|
+| (default) | Human-readable table | Terminal browsing |
+| `-o json` | Compact JSON | Piping to `jq`, API consumption |
+| `-o jsonl` | One JSON object per line | Streaming, log processing |
+
+## Common options
+
+All search commands support these shared options:
+
+| Option | Description |
+|--------|-------------|
+| `--country` | Vinted country code (default: `se`, env: `VINTED_COUNTRY`) |
+| `--price-min` | Minimum price |
+| `--price-max` | Maximum price |
+| `--condition` | Item condition filter |
+| `--brand-id` | Numeric Vinted brand ID filter |
+| `--size-id` | Numeric Vinted size ID filter |
+| `--catalog-id` | Numeric Vinted catalog ID (category) filter |
+| `--sort` | Sort order (`relevance`, `newest`, `oldest`, `price-asc`, `price-desc`) |
+| `-n`, `--limit` | Max results to display |
+| `-p`, `--page` | Page number |
+| `-o`, `--output` | Output format (`table`, `json`, `jsonl`) |
+| `--raw` | Full API response instead of slim fields |
+
+## Supported countries
+
+`se`, `fr`, `de`, `uk`, `pl`, `be`, `nl`, `it`, `es`, `at`, `lu`, `pt`, `cz`, `hu`, `ro`, `sk`, `lt`, `lv`, `ee`
+
+Use `vinted countries` to list all supported country codes.
+
+## Default country via environment variable
+
+```bash
+export VINTED_COUNTRY=de
+vinted search "jacke"   # searches vinted.de
+```
+
+## Agent integration
+
+The JSON output is designed for LLM agents and automation:
+
+```bash
+# Slim search results for an agent
+vinted search "nike air max" --sort price-asc -o json | jq '.results[:5]'
+
+# Stream listings line by line
+vinted search "vintage levi" -o jsonl
+
+# Price analysis
+vinted search "iphone 15" -o json | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+prices = [float(r['price']) for r in data['results'] if r.get('price')]
+print(f'Found {data[\"total\"]} listings')
+print(f'Price range: {min(prices):.0f} - {max(prices):.0f}')
+print(f'Average: {sum(prices)/len(prices):.0f}')
+"
+
+# Get full item details
+vinted item 1234567890 -o json
+```
+
+## License
+
+MIT

vinted_cli-0.1.0/README.md

@@ -0,0 +1,122 @@
+# vinted-cli
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Fast CLI for searching [Vinted](https://www.vinted.se).
+
+Primary target is vinted.se but can be configured to work with any Vinted country. Designed for agents, scripts, and quick terminal lookups. Minimal dependencies, structured output.
+
+## Install
+
+**From PyPI:**
+
+```bash
+pip install vinted-cli
+```
+
+**Upgrade:**
+
+```bash
+pip install --upgrade vinted-cli
+```
+
+## Usage
+
+### Search listings
+
+```bash
+vinted search "jeans"
+vinted search "iphone 15" --price-max 5000
+vinted search "nike" --condition very-good --sort price-asc
+vinted search "dress M" --sort newest -n 10
+vinted search "jacka" -o json | jq '.results[:3]'
+vinted search --catalog-id 1231          # browse a category without a query
+vinted search --price-max 100 --sort newest  # all cheap new listings
+```
+
+### Get item details
+
+```bash
+vinted item 1234567890
+vinted item 1234567890 -o json
+vinted item 1234567890 --country fr
+```
+
+### Browse filters
+
+```bash
+vinted countries                   # list all supported country codes
+vinted conditions                  # list item condition filters
+vinted catalogs                    # list the full catalog tree
+vinted catalogs --parent-id 2994   # list subcatalogs of Electronics
+```
+
+## Output formats
+
+| Flag | Format | Use case |
+|------|--------|----------|
+| (default) | Human-readable table | Terminal browsing |
+| `-o json` | Compact JSON | Piping to `jq`, API consumption |
+| `-o jsonl` | One JSON object per line | Streaming, log processing |
+
+## Common options
+
+All search commands support these shared options:
+
+| Option | Description |
+|--------|-------------|
+| `--country` | Vinted country code (default: `se`, env: `VINTED_COUNTRY`) |
+| `--price-min` | Minimum price |
+| `--price-max` | Maximum price |
+| `--condition` | Item condition filter |
+| `--brand-id` | Numeric Vinted brand ID filter |
+| `--size-id` | Numeric Vinted size ID filter |
+| `--catalog-id` | Numeric Vinted catalog ID (category) filter |
+| `--sort` | Sort order (`relevance`, `newest`, `oldest`, `price-asc`, `price-desc`) |
+| `-n`, `--limit` | Max results to display |
+| `-p`, `--page` | Page number |
+| `-o`, `--output` | Output format (`table`, `json`, `jsonl`) |
+| `--raw` | Full API response instead of slim fields |
+
+## Supported countries
+
+`se`, `fr`, `de`, `uk`, `pl`, `be`, `nl`, `it`, `es`, `at`, `lu`, `pt`, `cz`, `hu`, `ro`, `sk`, `lt`, `lv`, `ee`
+
+Use `vinted countries` to list all supported country codes.
+
+## Default country via environment variable
+
+```bash
+export VINTED_COUNTRY=de
+vinted search "jacke"   # searches vinted.de
+```
+
+## Agent integration
+
+The JSON output is designed for LLM agents and automation:
+
+```bash
+# Slim search results for an agent
+vinted search "nike air max" --sort price-asc -o json | jq '.results[:5]'
+
+# Stream listings line by line
+vinted search "vintage levi" -o jsonl
+
+# Price analysis
+vinted search "iphone 15" -o json | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+prices = [float(r['price']) for r in data['results'] if r.get('price')]
+print(f'Found {data[\"total\"]} listings')
+print(f'Price range: {min(prices):.0f} - {max(prices):.0f}')
+print(f'Average: {sum(prices)/len(prices):.0f}')
+"
+
+# Get full item details
+vinted item 1234567890 -o json
+```
+
+## License
+
+MIT

vinted_cli-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "vinted-cli"
+version = "0.1.0"
+description = "Fast CLI for searching Vinted — optimized for agents and scripting"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Paatsu" }]
+keywords = ["vinted", "cli", "search", "marketplace", "sweden", "fashion"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "click>=8.0",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/Paatsu/vinted-cli"
+Repository = "https://github.com/Paatsu/vinted-cli"
+Issues = "https://github.com/Paatsu/vinted-cli/issues"
+
+[project.scripts]
+vinted = "vinted-cli.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.9"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

vinted_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,175 @@
+"""Tests for Vinted CLI commands (mocked HTTP)."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from vinted_cli.cli import main
+
+SEARCH_RESPONSE = {
+    "items": [
+        {
+            "id": 1234567890,
+            "title": "Nike Air Max 90",
+            "price": "499",
+            "currency": "SEK",
+            "brand_title": "Nike",
+            "size_title": "42",
+            "status": "Very good",
+            "url": "https://www.vinted.se/items/1234567890-nike-air-max-90",
+            "user": {"login": "seller123"},
+            "photo": {"url": "https://images.vinted.se/1.jpg", "full_size_url": "https://images.vinted.se/1_full.jpg"},
+            "description": "Great condition Nike shoes",
+        }
+    ],
+    "pagination": {
+        "current_page": 1,
+        "total_pages": 5,
+        "total_count": 98,
+        "per_page": 20,
+    },
+}
+
+ITEM_RESPONSE = {
+    "item": {
+        "id": 1234567890,
+        "title": "Nike Air Max 90",
+        "price": "499",
+        "currency": "SEK",
+        "brand_title": "Nike",
+        "size_title": "42",
+        "status": "Very good",
+        "url": "https://www.vinted.se/items/1234567890-nike-air-max-90",
+        "user": {"login": "seller123"},
+        "description": "Great condition Nike shoes",
+    }
+}
+
+
+def _mock_search(*args, **kwargs):
+    return SEARCH_RESPONSE
+
+
+def _mock_get_item(*args, **kwargs):
+    return ITEM_RESPONSE
+
+
+class TestSearchCommand:
+    def test_table_output(self):
+        with patch("vinted_cli.cli.api.search", _mock_search):
+            result = CliRunner().invoke(main, ["search", "nike"])
+        assert result.exit_code == 0
+        assert "Nike Air Max 90" in result.output
+        assert "499 SEK" in result.output
+
+    def test_json_output_is_slim(self):
+        with patch("vinted_cli.cli.api.search", _mock_search):
+            result = CliRunner().invoke(main, ["search", "nike", "-o", "json"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert data["total"] == 98
+        listing = data["results"][0]
+        assert listing["id"] == 1234567890
+        assert listing["title"] == "Nike Air Max 90"
+        assert listing["price"] == "499"
+        # Slim output should not include raw photo object
+        assert "photo" not in listing or isinstance(listing["photo"], str)
+        # Slim output should not include description
+        assert "description" not in listing
+
+    def test_json_raw_output(self):
+        with patch("vinted_cli.cli.api.search", _mock_search):
+            result = CliRunner().invoke(main, ["search", "nike", "-o", "json", "--raw"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        listing = data["results"][0]
+        assert "description" in listing
+        assert isinstance(listing["photo"], dict)
+
+    def test_jsonl_output(self):
+        with patch("vinted_cli.cli.api.search", _mock_search):
+            result = CliRunner().invoke(main, ["search", "nike", "-o", "jsonl"])
+        assert result.exit_code == 0
+        lines = [line for line in result.output.strip().splitlines() if line]
+        assert len(lines) == 1
+        item = json.loads(lines[0])
+        assert item["id"] == 1234567890
+
+    def test_limit(self):
+        with patch("vinted_cli.cli.api.search", _mock_search):
+            result = CliRunner().invoke(main, ["search", "nike", "-o", "json", "-n", "1"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert len(data["results"]) == 1
+
+    def test_invalid_country(self):
+        result = CliRunner().invoke(main, ["search", "nike", "--country", "xx"])
+        assert result.exit_code == 1
+        assert "Unknown country" in result.output
+
+    def test_invalid_condition(self):
+        result = CliRunner().invoke(main, ["search", "nike", "--condition", "terrible"])
+        assert result.exit_code != 0
+
+    def test_table_output_shows_seller(self):
+        with patch("vinted_cli.cli.api.search", _mock_search):
+            result = CliRunner().invoke(main, ["search", "nike"])
+        assert "seller123" in result.output
+
+    def test_catalog_id_passed_to_api(self):
+        captured = {}
+
+        def capture_search(*args, **kwargs):
+            captured.update(kwargs)
+            return SEARCH_RESPONSE
+
+        with patch("vinted_cli.cli.api.search", capture_search):
+            result = CliRunner().invoke(main, ["search", "nike", "--catalog-id", "1231"])
+        assert result.exit_code == 0
+        assert captured.get("catalog_id") == "1231"
+
+    def test_search_without_query(self):
+        captured = {}
+
+        def capture_search(*args, **kwargs):
+            captured["query"] = args[0] if args else kwargs.get("query", "")
+            return SEARCH_RESPONSE
+
+        with patch("vinted_cli.cli.api.search", capture_search):
+            result = CliRunner().invoke(main, ["search", "--catalog-id", "1231"])
+        assert result.exit_code == 0
+        assert captured.get("query") == ""
+
+
+class TestItemCommand:
+    def test_table_output(self):
+        with patch("vinted_cli.cli.api.get_item", _mock_get_item):
+            result = CliRunner().invoke(main, ["item", "1234567890"])
+        assert result.exit_code == 0
+        assert "Nike Air Max 90" in result.output
+        assert "499 SEK" in result.output
+        assert "Nike" in result.output
+
+    def test_json_output(self):
+        with patch("vinted_cli.cli.api.get_item", _mock_get_item):
+            result = CliRunner().invoke(main, ["item", "1234567890", "-o", "json"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert data["item"]["title"] == "Nike Air Max 90"
+
+
+class TestInfoCommands:
+    def test_countries(self):
+        result = CliRunner().invoke(main, ["countries"])
+        assert result.exit_code == 0
+        assert "se" in result.output
+        assert "vinted.se" in result.output
+
+    def test_conditions(self):
+        result = CliRunner().invoke(main, ["conditions"])
+        assert result.exit_code == 0
+        assert "very-good" in result.output
+        assert "Very good" in result.output

vinted_cli-0.1.0/vinted_cli/__init__.py

@@ -0,0 +1 @@
+"""Vinted CLI — search Vinted from the terminal."""

vinted_cli-0.1.0/vinted_cli/api.py

@@ -0,0 +1,229 @@
+"""Vinted search API client."""
+
+from __future__ import annotations
+
+import logging
+import time
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+# Per-domain session cookie cache (lives for the duration of the process)
+_session_cache: dict[str, httpx.Cookies] = {}
+
+# Retry configuration
+_RETRY_ATTEMPTS = 3
+_RETRY_BACKOFF = 1.0          # seconds; doubles each attempt
+_RETRY_STATUS_CODES = {429, 500, 502, 503, 504}
+
+# Supported country code → domain mapping
+COUNTRIES: dict[str, str] = {
+    "se": "www.vinted.se",
+    "fr": "www.vinted.fr",
+    "de": "www.vinted.de",
+    "uk": "www.vinted.co.uk",
+    "pl": "www.vinted.pl",
+    "be": "www.vinted.be",
+    "nl": "www.vinted.nl",
+    "it": "www.vinted.it",
+    "es": "www.vinted.es",
+    "at": "www.vinted.at",
+    "lu": "www.vinted.lu",
+    "pt": "www.vinted.pt",
+    "cz": "www.vinted.cz",
+    "hu": "www.vinted.hu",
+    "ro": "www.vinted.ro",
+    "sk": "www.vinted.sk",
+    "lt": "www.vinted.lt",
+    "lv": "www.vinted.lv",
+    "ee": "www.vinted.ee",
+}
+
+# Vinted item condition status IDs
+CONDITIONS: dict[str, str] = {
+    "new-with-tags": "6",
+    "new-without-tags": "1",
+    "very-good": "2",
+    "good": "3",
+    "satisfactory": "4",
+}
+
+CONDITION_LABELS: dict[str, str] = {
+    "new-with-tags": "New with tags",
+    "new-without-tags": "New without tags",
+    "very-good": "Very good",
+    "good": "Good",
+    "satisfactory": "Satisfactory",
+}
+
+# Sort order mapping
+SORT_MAP: dict[str, str] = {
+    "relevance": "relevance",
+    "newest": "newest_first",
+    "oldest": "oldest_first",
+    "price-asc": "price_low_to_high",
+    "price-desc": "price_high_to_low",
+}
+
+HEADERS = {
+    "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:125.0) Gecko/20100101 Firefox/125.0",
+    "Accept": "application/json, text/plain, */*",
+    "Accept-Language": "sv-SE,sv;q=0.9,en-US;q=0.8,en;q=0.7",
+}
+
+
+def _base_url(domain: str) -> str:
+    return f"https://{domain}"
+
+
+def _get_session(domain: str) -> httpx.Cookies:
+    """Return cached session cookies for *domain*, fetching them if not yet cached."""
+    if domain in _session_cache:
+        log.debug("Reusing cached session cookie for %s", domain)
+        return _session_cache[domain]
+
+    log.debug("Fetching session cookie from https://%s/", domain)
+    r = httpx.get(
+        f"https://{domain}/",
+        headers=HEADERS,
+        timeout=15,
+        follow_redirects=True,
+    )
+    log.debug("Session response: %s, cookies: %s", r.status_code, dict(r.cookies))
+    r.raise_for_status()
+    _session_cache[domain] = r.cookies
+    return r.cookies
+
+
+def _request_with_retry(url: str, *, params=None, cookies: httpx.Cookies) -> httpx.Response:
+    """GET *url* with exponential-backoff retries on transient errors (429, 5xx)."""
+    delay = _RETRY_BACKOFF
+    for attempt in range(1, _RETRY_ATTEMPTS + 1):
+        r = httpx.get(url, params=params, headers=HEADERS, cookies=cookies, timeout=15, follow_redirects=True)
+        if r.status_code not in _RETRY_STATUS_CODES:
+            return r
+        if attempt == _RETRY_ATTEMPTS:
+            break
+        # Respect Retry-After header if present (429 often sends it)
+        retry_after = r.headers.get("Retry-After")
+        wait = float(retry_after) if retry_after and retry_after.isdigit() else delay
+        log.debug("HTTP %s — retrying in %.1fs (attempt %d/%d)", r.status_code, wait, attempt, _RETRY_ATTEMPTS)
+        time.sleep(wait)
+        delay *= 2
+    r.raise_for_status()
+    return r  # unreachable after raise_for_status, satisfies type checkers
+
+
+def _resolve_country(country: str) -> str:
+    domain = COUNTRIES.get(country.lower())
+    if not domain:
+        raise ValueError(f"Unknown country '{country}'. Valid: {', '.join(sorted(COUNTRIES))}")
+    return domain
+
+
+def _resolve_condition(name: str) -> str:
+    code = CONDITIONS.get(name.lower())
+    if not code:
+        raise ValueError(f"Unknown condition '{name}'. Valid: {', '.join(sorted(CONDITIONS))}")
+    return code
+
+
+def search(
+    query: str = "",
+    *,
+    country: str = "se",
+    price_min: int | None = None,
+    price_max: int | None = None,
+    condition: str | None = None,
+    brand_id: str | None = None,
+    size_id: str | None = None,
+    catalog_id: str | None = None,
+    sort: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> dict:
+    """Search listings on Vinted.
+
+    brand_id, size_id, and catalog_id are numeric Vinted API IDs (e.g. brand_id="53" for Nike).
+    Include brand or size terms in the query text for free-text filtering instead.
+    """
+    domain = _resolve_country(country)
+    cookies = _get_session(domain)
+
+    params: list[tuple[str, str]] = [
+        ("per_page", str(per_page)),
+        ("page", str(page)),
+    ]
+    if query:
+        params.append(("search_text", query))
+    if price_min is not None:
+        params.append(("price_from", str(price_min)))
+    if price_max is not None:
+        params.append(("price_to", str(price_max)))
+    if condition:
+        params.append(("status_ids[]", _resolve_condition(condition)))
+    if brand_id:
+        params.append(("brand_ids[]", brand_id))
+    if size_id:
+        params.append(("size_ids[]", size_id))
+    if catalog_id:
+        params.append(("catalog_ids[]", catalog_id))
+    if sort:
+        params.append(("order", SORT_MAP.get(sort, sort)))
+
+    log.debug("GET https://%s/api/v2/catalog/items params=%s", domain, params)
+    r = _request_with_retry(f"https://{domain}/api/v2/catalog/items", params=params, cookies=cookies)
+    log.debug("Search response: %s", r.status_code)
+    log.debug("Response body: %s", r.text[:2000])
+    r.raise_for_status()
+    return r.json()
+
+
+def get_item(item_id: int | str, *, country: str = "se") -> dict:
+    """Fetch full details for a specific item."""
+    domain = _resolve_country(country)
+    cookies = _get_session(domain)
+
+    log.debug("GET https://%s/api/v2/items/%s", domain, item_id)
+    r = _request_with_retry(f"https://{domain}/api/v2/items/{item_id}", cookies=cookies)
+    log.debug("Item response: %s", r.status_code)
+    log.debug("Response body: %s", r.text[:2000])
+    r.raise_for_status()
+    return r.json()
+
+
+def fetch_catalogs(*, country: str = "se") -> list[dict]:
+    """Fetch the full catalog tree from the Vinted API."""
+    domain = _resolve_country(country)
+    cookies = _get_session(domain)
+
+    params = [("page", "1"), ("time", str(int(time.time())))]
+    log.debug("GET https://%s/api/v2/catalog/initializers", domain)
+    r = _request_with_retry(
+        f"https://{domain}/api/v2/catalog/initializers", params=params, cookies=cookies
+    )
+    r.raise_for_status()
+    data = r.json()
+    return data.get("dtos", {}).get("catalogs", [])
+
+
+def _walk_catalogs(catalogs: list[dict], parent_id: int | None, depth: int) -> list[dict]:
+    """Recursively walk catalog tree, collecting all nodes under parent_id."""
+    results = []
+    for cat in catalogs:
+        if parent_id is None or cat.get("id") == parent_id:
+            # Found the root we care about — collect everything under it
+            results.append({"id": cat["id"], "title": cat["title"], "depth": depth})
+            for child in cat.get("catalogs") or []:
+                results.extend(_walk_catalogs([child], None, depth + 1))
+        else:
+            # Keep searching deeper
+            results.extend(_walk_catalogs(cat.get("catalogs") or [], parent_id, depth))
+    return results
+
+
+def list_catalogs(*, country: str = "se", parent_id: int | None = None) -> list[dict]:
+    """Return a flat list of catalogs, optionally scoped to a parent catalog ID."""
+    catalogs = fetch_catalogs(country=country)
+    return _walk_catalogs(catalogs, parent_id, 0)

vinted_cli-0.1.0/vinted_cli/cli.py

@@ -0,0 +1,181 @@
+"""Vinted CLI — search Vinted from the terminal."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+import click
+
+from . import api, format
+
+DEFAULT_COUNTRY = os.environ.get("VINTED_COUNTRY", "se")
+
+SORT_CHOICES = ["relevance", "newest", "oldest", "price-asc", "price-desc"]
+
+
+@click.group()
+@click.version_option()
+@click.option("--debug", is_flag=True, envvar="VINTED_DEBUG", help="Enable debug logging.")
+@click.pass_context
+def main(ctx: click.Context, debug: bool):
+    """Search Vinted from the command line.
+
+    Fast, minimal CLI for searching Vinted. Defaults to vinted.se.
+    Designed for scripting, agents, and quick lookups.
+
+    Set the VINTED_COUNTRY environment variable to change the default country.
+    """
+    if debug:
+        logging.basicConfig(level=logging.DEBUG, format="%(levelname)s %(name)s: %(message)s", stream=sys.stderr)
+
+
+@main.command()
+@click.argument("query", default="", required=False)
+@click.option("--country", default=DEFAULT_COUNTRY, show_default=True, help="Country code (se, fr, de, uk, pl, …)")
+@click.option("--price-min", type=int, help="Minimum price")
+@click.option("--price-max", type=int, help="Maximum price")
+@click.option(
+    "--condition",
+    type=click.Choice(["new-with-tags", "new-without-tags", "very-good", "good", "satisfactory"], case_sensitive=False),
+    help="Item condition",
+)
+@click.option("--brand-id", help="Numeric Vinted brand ID (e.g. 53 for Nike; include brand in query for free-text)")
+@click.option("--size-id", help="Numeric Vinted size ID (include size in query for free-text, e.g. 'jeans XL')")
+@click.option("--catalog-id", help="Numeric Vinted catalog ID to filter by category (use `vinted catalogs` to list them)")
+@click.option("--sort", type=click.Choice(SORT_CHOICES, case_sensitive=False), help="Sort order")
+@click.option("-n", "--limit", type=int, help="Max results to show")
+@click.option("-p", "--page", type=int, default=1, help="Page number")
+@click.option("-o", "--output", type=click.Choice(["table", "json", "jsonl"]), default="table", help="Output format")
+@click.option("--raw", is_flag=True, help="Full API response (default: slim agent-friendly fields)")
+def search(
+    query: str,
+    country: str,
+    price_min: int | None,
+    price_max: int | None,
+    condition: str | None,
+    brand_id: str | None,
+    size_id: str | None,
+    catalog_id: str | None,
+    sort: str | None,
+    limit: int | None,
+    page: int,
+    output: str,
+    raw: bool,
+):
+    """Search listings on Vinted.
+
+    QUERY is optional — omit it to browse without a text filter.
+
+    \b
+    Examples:
+        vinted search "jeans"
+        vinted search "iphone 15" --price-max 5000
+        vinted search "nike" --condition very-good --sort price-asc
+        vinted search "dress M" --sort newest -n 10
+        vinted search "jacka" -o json | jq '.results[:3]'
+        vinted search "jacka" --country se -o jsonl
+        vinted search "sneakers" --catalog-id 1231
+        vinted search --catalog-id 1231 --sort newest
+        vinted search --price-max 100
+    """
+    try:
+        data = api.search(
+            query,
+            country=country,
+            price_min=price_min,
+            price_max=price_max,
+            condition=condition,
+            brand_id=brand_id,
+            size_id=size_id,
+            catalog_id=catalog_id,
+            sort=sort,
+            page=page,
+        )
+        format.print_results(data, output=output, limit=limit, raw=raw)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("item_id")
+@click.option("--country", default=DEFAULT_COUNTRY, show_default=True, help="Country code (se, fr, de, uk, pl, …)")
+@click.option("-o", "--output", type=click.Choice(["table", "json"]), default="table", help="Output format")
+def item(item_id: str, country: str, output: str):
+    """Get full details for a specific item.
+
+    \b
+    Examples:
+        vinted item 1234567890
+        vinted item 1234567890 -o json
+        vinted item 1234567890 --country fr
+    """
+    try:
+        data = api.get_item(item_id, country=country)
+        format.print_item(data, output=output)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+def countries():
+    """List supported country codes.
+
+    \b
+    Examples:
+        vinted countries
+    """
+    print("Supported country codes:\n")
+    for code, domain in sorted(api.COUNTRIES.items()):
+        print(f"  {code:<6}  {domain}")
+
+
+@main.command()
+def conditions():
+    """List item condition filters.
+
+    \b
+    Examples:
+        vinted conditions
+    """
+    print("Item conditions:\n")
+    for key, label in api.CONDITION_LABELS.items():
+        print(f"  {key:<20}  {label}")
+
+
+@main.command()
+@click.option("--country", default=DEFAULT_COUNTRY, show_default=True, help="Country code")
+@click.option("--parent-id", type=int, default=None, help="Show only subcatalogs of this catalog ID")
+@click.option("-o", "--output", type=click.Choice(["table", "json"]), default="table", help="Output format")
+def catalogs(country: str, parent_id: int | None, output: str):
+    """List Vinted catalog IDs and their names.
+
+    \b
+    Examples:
+        vinted catalogs
+        vinted catalogs --parent-id 2994
+        vinted catalogs --parent-id 2994 -o json
+        vinted catalogs --country fr --parent-id 2994
+    """
+    try:
+        entries = api.list_catalogs(country=country, parent_id=parent_id)
+        if output == "json":
+            import json
+            print(json.dumps(entries, ensure_ascii=False))
+            return
+        if not entries:
+            click.echo("No catalogs found.", err=True)
+            return
+        for entry in entries:
+            indent = "  " * entry["depth"]
+            print(f"{indent}{entry['id']:<8}  {entry['title']}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

vinted_cli-0.1.0/vinted_cli/format.py

@@ -0,0 +1,126 @@
+"""Output formatting for Vinted CLI."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+MAX_DESCRIPTION_LENGTH = 200
+
+
+def _json_compact(data: Any) -> str:
+    return json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+
+
+def _extract_price(item: dict) -> tuple[str, str]:
+    """Return (amount, currency) handling both flat and nested price formats."""
+    price = item.get("price")
+    if isinstance(price, dict):
+        return price.get("amount", "—"), price.get("currency_code", "")
+    # Legacy flat format
+    return str(price) if price else "—", item.get("currency", "")
+
+
+def _slim(item: dict) -> dict:
+    """Strip an item to agent-essential fields."""
+    amount, currency = _extract_price(item)
+    out: dict[str, Any] = {
+        "id": item.get("id"),
+        "title": item.get("title"),
+        "price": amount,
+        "currency": currency,
+        "brand": item.get("brand_title"),
+        "size": item.get("size_title"),
+        "condition": item.get("status"),
+        "seller": item.get("user", {}).get("login"),
+        "url": item.get("url"),
+    }
+    photo = item.get("photo")
+    if isinstance(photo, dict):
+        out["photo"] = photo.get("url") or photo.get("full_size_url")
+    # Remove None values for cleaner output
+    return {k: v for k, v in out.items() if v is not None}
+
+
+def print_results(data: dict, *, output: str = "table", limit: int | None = None, raw: bool = False) -> None:
+    """Print search results."""
+    items = data.get("items", [])
+    total = data.get("pagination", {}).get("total_count", len(items))
+
+    if limit:
+        items = items[:limit]
+
+    if output == "json":
+        results = items if raw else [_slim(i) for i in items]
+        print(_json_compact({"total": total, "results": results}))
+        return
+
+    if output == "jsonl":
+        for item in items:
+            print(_json_compact(item if raw else _slim(item)))
+        return
+
+    if not items:
+        print("No results found.", file=sys.stderr)
+        return
+
+    print(f"Found {total:,} listings (showing {len(items)}):\n")
+
+    for item in items:
+        title = item.get("title", "Untitled")
+        price, currency = _extract_price(item)
+        brand = item.get("brand_title", "")
+        size = item.get("size_title", "")
+        condition = item.get("status", "")
+        seller = item.get("user", {}).get("login", "")
+        url = item.get("url", "")
+
+        price_str = f"{price} {currency}".strip() if price else "—"
+        meta_parts = [p for p in [brand, size, condition] if p]
+        meta_str = " · ".join(meta_parts) if meta_parts else ""
+
+        print(f"  {title}")
+        print(f"  {price_str}" + (f" · {meta_str}" if meta_str else ""))
+        if seller:
+            print(f"  Seller: {seller}")
+        print(f"  {url}")
+        print()
+
+
+def print_item(data: dict, *, output: str = "table") -> None:
+    """Print item details."""
+    if output == "json":
+        print(_json_compact(data))
+        return
+
+    item = data.get("item", data)
+
+    if "error" in item:
+        print(f"Error: {item['error']}", file=sys.stderr)
+        return
+
+    title = item.get("title", "Untitled")
+    price, currency = _extract_price(item)
+    brand = item.get("brand_title", "")
+    size = item.get("size_title", "")
+    condition = item.get("status", "")
+    description = item.get("description", "")
+    seller = item.get("user", {}).get("login", "")
+    url = item.get("url", "")
+
+    price_str = f"{price} {currency}".strip()
+    print(f"  {title}")
+    print(f"  {price_str}")
+    if brand:
+        print(f"  Brand: {brand}")
+    if size:
+        print(f"  Size: {size}")
+    if condition:
+        print(f"  Condition: {condition}")
+    if seller:
+        print(f"  Seller: {seller}")
+    if description:
+        print(f"  Description: {description[:MAX_DESCRIPTION_LENGTH]}")
+    if url:
+        print(f"  {url}")