vinted is a terminal cli for vinted that lets you search the catalog with the filters the web has, watch searches, items, and members for changes, and chat with sellers, all from your own account. it compiles to one static Go binary. output is json by default so everything pipes into jq. --format pretty is for humans.
documentation | command demos | npm | github
why
if you already use vinted and want it in the terminal, this cli gives you a practical path without the browser. search once and keep the results as a stream of events, talk to sellers from your own account, and filter by catalog, brand, size, condition and colour, all from one static binary with no daemon. output is json by default, so scripts, agents, and shell pipelines all read the same thing.
quickstart
linux or macos
install the binary with curl:
curl -fsSL https://vinted.micr.dev/install.sh | sh
vinted --version
the installer places vinted in ~/.local/bin (override with VINTED_INSTALL_DIR).
windows
install via scoop:
scoop bucket add microck https://github.com/Microck/scoop-bucket
scoop install vinted
vinted --version
using a package manager
# homebrew
brew install Microck/tap/vinted
# npm
npm install -g vinted-cli
# arch linux (aur)
yay -S vinted-cli-bin
go install
go install github.com/Microck/vinted-cli/cmd/vinted@latest
vinted --version
every release ships checksums.txt with a github provenance attestation:
gh release download --repo Microck/vinted-cli --pattern checksums.txt
gh attestation verify checksums.txt --repo Microck/vinted-cli
check that the install works:
vinted --version
vinted doctor
doctor checks that the config loads, every sink is valid, the proxy setting parses, no cooldown is running, the vinted site answers, the session works, and the state of the watch schedule.
auth
vinted keeps your login in browser cookies, so the cli imports them instead of asking for a password. email, google, apple, and facebook accounts all work the same way.
- log in on your vinted domain in your browser (www.vinted.com, www.vinted.fr, www.vinted.es, ...)
- export cookies for that site with an extension such as cookie-editor (netscape
cookies.txtor json; a whole-browser export works too) - run
vinted auth loginand paste the file path, or pass--cookies FILE
# interactive prompt (paste a cookie file path or a cookie header)
vinted auth login
# import from an exported cookie file
vinted auth login --cookies ~/Downloads/cookies.txt
# pick the vinted domain explicitly (default: the host the cookies came from)
vinted auth login --cookies cookies.txt --domain vinted.fr
# read from stdin
cat cookies.txt | vinted auth login --cookies-stdin
the cli needs refresh_token_web from the export (and normally access_token_web with it). auth login reads the export and hands it to the bundled galleton session engine, an encrypted vault next to credentials.toml; after that the cli never holds the cookies again. the engine renews the access token through vinted's own refresh endpoint before it expires, keeps the rotated cookies, and is the only thing that ever spends the single-use refresh token. after importing, log out of that browser session (or just log in again there): the browser still holds the refresh token the engine spends. vinted can still expire or revoke a session, so you may need to log in again.
check session status or refresh by hand:
vinted auth status # local, offline
vinted auth status --check # asks the engine and vinted
vinted auth refresh # renew now
the engine starts with the first command that needs the account and stops ten seconds after the last one. to keep it renewing between commands (and after a reboot, once you log in), run vinted auth service enable; vinted auth service status / disable / stop / run manage it. details: docs/galleton.md.
after a successful vinted auth login in a terminal it asks keep this login alive in the background? [Y/n]; yes runs vinted auth service enable for you. --service / --no-service answer without asking (--service works with --no-input); --no-input, CI and a non-terminal skip the question. without the service, vinted auth status and vinted doctor warn (without failing) when the login's refresh token expires within 48 hours.
run multiple accounts side by side using profiles:
vinted auth login --cookies alt.txt --profile alt
vinted profile list
vinted profile use alt
vinted search "levis 501" --profile alt
upgrading from a version before the session engine: run vinted auth login once with a fresh export. older versions kept the cookies in credentials.toml; the new one never reads them and drops them on its first write.
updates
vinted update
vinted update --check
vinted update --yes
eligible interactive commands check for a new stable release at most once a day and ask Update? [Y/n]. auth, watch, completion, help, and update are excluded from automatic checks. scripts, MCP, and --no-input never prompt or check automatically. set VINTED_NO_UPDATE_CHECK=1 to disable automatic checks. npm, Homebrew, Scoop, and AUR installs update through their package manager; direct binaries use checksum-verified release archives. development and prerelease builds are not replaced.
auth model
public reads always use an anonymous session, even when the selected profile has a stored account session. a stale or unavailable session engine does not block search, item or member reads. authenticated commands still require that profile and never fall back to anonymous requests. both paths keep the configured proxy, request pacing and shared cooldown.
vinted gates some features behind its own account verification: chat (reading the inbox too), offers, reservations, favorites and every change to your own items answer code 115 until vinted has verified the account. the cli turns that into exit 3 with a link to the verification page. search, item and member pages, saved searches and watches work without it.
staying unblocked
vinted sits behind datadome and cloudflare. they watch for traffic that looks automated, and when they decide yours is, they block the session ("Se ha bloqueado tu sesión", unusual activity) and sometimes the whole ip for hours. a blocked session can take your browser login down with it. the cli is built to stay well under that line, and it cannot be talked out of it:
- one request every 2 seconds per site, shared by every process. all
vintedprocesses and profiles on the machine queue behind one another through a small state file ($XDG_STATE_HOME/vinted-cli/throttle.json, locked while it is updated), with up to 1s of random jitter on every gap. raise it withvinted config set request_interval 5s; it cannot go below 1s. - a block stops everything. a captcha page, a datadome or cloudflare block, an http 429, or an unexplained 403 ends the command with exit
5, is never retried, and starts a 6 hour cooldown (longer if vinted'sRetry-Afterasks for it). until it ends, every command fails at once with the time left and sends nothing, and the session engine is paused for as long, so it does not renew the session meanwhile.vinted cooldownshows it,vinted doctorandvinted auth statustoo.vinted cooldown clearlifts both early; only do that once vinted works normally in your browser. - small requests only.
search --pagesis capped at 5, a search watch reads at most 5 pages and a seller watch at most 10 wardrobe pages per check, and one command (one watch tick, one mcp tool call) may send at most 60 requests. - slow schedules.
watch add,watch runandwatch service installrefuse intervals under 15 minutes; scheduled runs start after a random delay of up to a tenth of the interval, and watches are checked one after another.chat openpolls every 30s (floor 10s). - no needless requests. the csrf token and the guest session are cached in the same state file (0600), so a command does not reload the home page each time; one keep-alive connection serves a whole command; every request carries the same chrome-on-linux headers, with client hints that match the user agent and the site's language.
what you should do:
- keep intervals generous. a few watches every 15-30 minutes is fine; dozens every 15 minutes is not.
- run the cli from the same network you browse vinted from. datacenter, vps and commercial vpn ip ranges are flagged far faster than a home connection.
- if you need a proxy, set
proxyin config.toml orVINTED_PROXY(socks5h://127.0.0.1:1080,http://host:port). all vinted traffic then goes through it, the session engine's token renewals included, and if it is unreachable the request fails with exit6; it never falls back to a direct connection. a running engine keeps the proxy it started with, and a command with a different one refuses to use it. config.toml is world-readable, so a proxy with credentials goes inVINTED_PROXYonly (and then cannot be baked intowatch service installorauth service enable). - when you hit a block: stop, wait out the cooldown, open vinted in your normal browser and solve any captcha there. if the session stays blocked, export fresh cookies and run
vinted auth loginagain.
none of this makes automated use invisible. vinted can still block the session; the cli only makes it much less likely and stops making it worse when it happens.
command surface
global flags: --profile, --format json|jsonl|pretty|toon, --no-color, --error-format text|json, --no-input, --debug.
shell completion
# zsh
vinted completion zsh > "${fpath[1]}/_vinted"
# bash
vinted completion bash > /etc/bash_completion.d/vinted
# fish
vinted completion fish > ~/.config/fish/completions/vinted.fish
# powershell
vinted completion powershell >> $PROFILE
examples
vinted search "levis 501" --price-to 30 --order newest_first --format pretty
vinted brand search nike
vinted search "air max" --brand 53 --size 208 --condition very_good --limit 20
vinted search filters --catalog 1845 --format pretty
vinted search --catalog 1845 --pattern 21 --color 9 --material 303 --price-to 40 --currency USD
vinted item show https://www.vinted.com/items/4923018331-levis-501 --seller --format pretty
vinted item images 4923018331 --download ./photos --limit 3
vinted watch add search "levis 501" --price-to 30 --name levis --notify phone
vinted watch check --all --format jsonl | jq -r 'select(.type=="item.price_changed") | .item.url'
vinted watch service install --interval 30m
vinted chat list --format pretty
vinted chat start 4923018331 "hi, is this still available?"
echo "would you take 20?" | vinted chat send 18273645 -
vinted chat offer 18273645 20
vinted alert list --format pretty
vinted watch add search --from-alert 4650918777 --name saved
vinted item create --title "levi's 501" --description "worn twice" --price 25 \
--category 1840 --condition "very good" --size "W32" --brand "levi's" --color blue \
--image front.jpg --image back.jpg
vinted item edit 4923018331 --price 20
vinted item hide 4923018331
vinted item delete 4923018331 --yes
what it looks like
these recordings use public listings. the watch writes only to its isolated local demo database. see the command demo gallery for search, filters, item details, and watch events.
inspect a listing
discover and apply filters
track changes with a watch
watches save a search locally; each check reports what changed.
sinks config
a sink is a few lines of config:
[sinks.phone]
type = "ntfy"
url = "https://ntfy.sh"
topic = "vinted-deals"
[sinks.discord]
type = "webhook"
url = "https://discord.com/api/webhooks/..."
template = "discord"
[sinks.script]
type = "exec"
command = ["~/bin/on-vinted-event"] # event json on stdin
exit codes
0 ok, 1 generic, 2 usage (including a refused interval, --pages over the cap, or a command past its 60-request budget), 3 auth, 4 not found, 5 blocked by vinted's bot protection or inside the cooldown that follows (do not retry; see staying unblocked), 6 network (including an unreachable proxy), 7 vinted changed its api or pages. stderr carries a prefilled issue link. 130 interrupted.
building from source
git clone https://github.com/Microck/vinted-cli && cd vinted-cli
make build # bin/vinted
make check # vet, staticcheck, tests, gofmt
documentation
full docs live at vinted.micr.dev/docs. install, the cookie export walkthrough, the command reference generated from the binary, exit codes, sinks, and scheduling. the site source is in docs-site.
- docs/cli-spec.md: the interface contract and every endpoint the cli uses
- AGENTS.md: vocabulary
- docs/adr: decisions
contributing
issues and pull requests are welcome. when vinted changes something, the cli prints a prefilled issue link. that is the most useful report you can file.
disclaimer
this is an unofficial client. vinted has no public api for members, and its terms and conditions prohibit automated access, scraping, and using the platform other than through its own interfaces. the stated remedy is restricting or closing the account. use it with an account you are willing to lose, keep the check interval reasonable, and do not use it to spam sellers. not affiliated with vinted.