All guides

The command line

Members who use the Barberry command line, and anyone who wants to ask an assistant about their wines

Last updated 9 November 2026

What this is

barberry is the Barberry Garden command line. It reads what the site shows you: the catalog of wines, your own tasting notes and the ones Barberry published, and the countries, regions, appellations and grapes the catalog uses. It prints them as a table at a terminal, or as JSON for a script or an assistant.

It also writes what you tell it to: your tasting notes (new ones, changes, and deleting one), your cellar (bottles you bought, opened, moved, sold or put right), a wine the catalog doesn't have, and, if you host or speak at a tasting, a participant's score. Publishing a note, choosing who reads it, signing up for events and paying stay on the site.

Who can use it

Every registered member can use it. Without a membership it works on a free allowance: up to 120 requests a minute, 20 changes a minute and 1000 requests a day (a day ends at midnight UTC). Past it, a command stops and says it was the free allowance, when to try again, and that a membership raises it; any membership, from Reader up, lifts it to what members have. What each command reads still follows your membership, as on the site: Barberry's notes and write-ups for members stay for members, and your cellar comes with Contributor.

Install it

On a Mac or on Linux, with Homebrew:

brew install barberry-io/tap/barberry

brew upgrade barberry keeps it current, and each release on the tap's releases page says what changed in it. If your build is too old for the server, it says so and tells you to run brew upgrade barberry, instead of failing in odd ways.

Sign in

barberry login

It shows a short code and a link. Open the link on barberry.io while signed in, check the code, and approve. The command line then keeps a token of its own:

  • on a Mac, in your login keychain, where an upgrade reads it without asking for your password again;
  • on Linux, in your system keychain, or, on a computer without one (a server, a container), in ~/.config/barberry/tokens.json, a file only you can read.

barberry login says where it went, and what to try first. barberry me shows who you are signed in as: your name, your membership, your currency, and whether new notes start as drafts (--format json for all of it). barberry logout signs the computer out. Every computer you sign in from is listed under "Signed-in terminals and connected apps" on your account page, where you can sign any of them out.

A token in BARBERRY_API_TOKEN is used instead of the keychain.

For what no command does yet, barberry api sends one request to the API as you and prints the answer: barberry api GET /v1/venues, or barberry api PATCH /v1/notes/NOTE_ID -d '{"revision": 3, "score": 4.5}' (-d @file.json reads the body from a file, -d @- from standard input). It sends your token itself and only to Barberry's API: a path is read from the API's address, and a URL to anywhere else is refused. A write goes out with an idempotency key, and the command sends it again only when it surely wasn't applied. When its answer is lost, it says the key: pass it back with --idempotency-key to send the write again, and an endpoint that takes the key applies it once. --verbose shows the request without the token.

barberry token prints the token itself. Avoid it in scripts: shell tracing (set -x), curl -v and process lists (ps) show it to anyone who reads them. Use barberry api instead.

Find wines

barberry wines list takes words of a wine's name, producer or vintage, and filters that all have to match:

barberry wines list barolo --vintage 2010..2016
barberry wines list --country Italy --grape Nebbiolo --score 4.5..
barberry wines list --tasted --sort my-score
barberry wines list --region Burgundy --not-tasted --colour red
  • --country, --region, --grape: by name or id. A region includes the regions and appellations inside it, and a grape is found by the other names it goes by too.
  • --colour (red, white, rose or unknown; an orange wine is white here), --type wine or --type sake, --sparkling, --still.
  • --vintage, --score (Barberry's score) and --my-score (yours) take a value or a range: 4.5.., ..2019, 2015..2019.
  • --tasted and --not-tasted: the wines you have a note of, or the ones you haven't. Drafts don't count.
  • --sort: score, my-score, vintage, name or newest.
  • --limit and --all for how many to print.

barberry wines show ID shows one wine as its page has it, what Barberry wrote about it, and every note of it you may read.

Read notes

barberry notes list --mine
barberry notes list --barberry --score 4.7..
barberry notes list --since 2026-01-01 --sort score

You read your own notes, drafts and private ones included, and the notes Barberry published. Barberry's notes scored 4.7 or less are for members: without a membership you see their scores, not their words, as on the site. A note of yours from a blind pour names the pour until the wine is revealed. Barberry's notes from a tasting show once the host finalizes its scores.

Where a wine was tasted, at which event and with whom shows on the notes of tastings you were at: your own, a note that names you in its company, and a note from an event you took part in. In the JSON forms these are place, event and company.

Your cellar

If you keep a cellar on Barberry, the command line reads it:

barberry cellar list
barberry cellar list --region Champagne --location Cave --price ..3000 --currency UAH --not-tasted
barberry cellar list --status consumed --sort purchased
barberry cellar locations

cellar list shows the bottles you have to open, by where you keep them: the wine, the location and spot, what each cost and in US dollars, and how many bottles of that wine you have. It takes the wine filters of wines list and words of the name, and:

  • --location and --spot: where a bottle is kept, typed as you like (case and accents don't matter).
  • --price with --currency: what it cost, a value or a range, in the currency you name (US dollars unless you say). A bottle bought in another currency compares at the rates of the day you bought it.
  • --status: available (the default), consumed, sold or all.
  • --sort: location, number, wine, purchased, price or vintage.

cellar locations lists each place you keep bottles and how many are there.

The cellar comes with the Contributor membership. Without it, cellar list says so and links to the pricing page, and export leaves the cellar out with the same note.

Write notes, keep your cellar

barberry notes add --wine ID --score 4.3 --note "Salty, long." --bottle BOTTLE_ID
barberry notes add --hint "Georgian orange, Vika brought" --colour white --score 4
barberry cellar open BOTTLE_ID
barberry cellar add WINE_ID --count 12 --price 850 --currency UAH --shop "Good Wine"
barberry wines add --producer-name "Domaine Three Sisters" --name "Les Coteaux" --vintage 2021 --colour red --place Beaujolais
barberry notes edit NOTE_ID --score 4.2
barberry notes edit NOTE_ID --place home --add-company MEMBER_ID
barberry notes delete NOTE_ID

notes add saves a tasting note the way you keep yours: a draft if you keep your notes as drafts, otherwise a finished note only you can read, which you can make public on the site. --draft keeps it a draft either way. It prints the link where you find it. It names the wine by its id (from wines list), or, for one the catalog doesn't have, by your own words with --hint and its colour (an orange wine is white here); a note of your own words is always a draft, where you link it to the wine. --score, --note and --date (today unless you say) are yours to give. --bottle ties the note to one of your bottles (its id is the last column of cellar list) and marks it opened that day.

cellar add WINE_ID adds bottles you bought: --count, the --price of one bottle and its --currency (yours unless you say), --date (today unless you say), --shop, and where you keep them with --location and --spot. A purchase stays yours, as on the site: what you paid never becomes the wine's price in the catalog.

cellar move BOTTLE_ID... --location Fridge moves bottles (--spot within the place). cellar edit BOTTLE_ID puts right what a bottle says of its purchase: --price, --date, --shop, --comment, or --asking, what you'd let it go for. cellar sell BOTTLE_ID --price 1200 --buyer Vika marks a bottle sold for money that came in outside Barberry, and cellar unsell takes that back; a sale charged to a member's balance is made on the site. cellar restore puts a bottle you marked opened by mistake back. cellar remove takes a bottle out of your cellar for good, and asks first.

wines add adds a wine the catalog doesn't have, so you can add bottles of it: its --name, --colour, the producer by --producer ID or a new one by --producer-name, and --vintage, --place and --grape by name. --sparkling for a wine with bubbles. --sweetness takes the label's words on that wine's scale: "off-dry" or "semi-sweet" for a still wine, "Brut Nature" or "demi-sec" with --sparkling. It waits for Barberry's review, and only you see it until then. Look for it first with wines list.

cellar open marks a bottle opened without a note. Bottles come with the cellar, which comes with the Contributor membership. --bottle goes with --wine, not --hint. Without --date, both take today on your computer. Each command applies once, even when it has to try again.

notes edit ID changes one of your notes, published or not: --score, --note (new words in place of the old), --date, --wine, who reads it, where you tasted it and who was there, and nothing else. A bottle the note opened is opened on the new day. --visibility is private (you, and Barberry's admins) or public. --place takes home for your home, home:MEMBER_ID for a member's home, a venue's id from venues list, or the place in your own words ("Wine Bureau, Podil"); --clear-place takes it off. --company names who was there by member id and replaces the whole list, so anyone you leave out is taken off; --add-company and --remove-company add or take off one person and keep the rest, and --no-company says nobody was. A note written at an event keeps the event's company.

members list Olena finds members by the name they go by, with the ids --company and --add-company take; members list --recent company lists the people your notes name most lately.

venues list lists your venues with their ids, and venues add --name "Wine Bureau, Podil" adds one (with --address and an https --url if you like).

notes delete ID deletes one of your notes. It shows you the note and asks before it deletes, since a deleted note can't be brought back; --yes skips the question, for a script.

Events

barberry events list
barberry events list --mine
barberry events list --past
barberry events show EVENT_ID

events list shows what's on: when and where, how many seats are taken, the price (if you may sign up; otherwise whom to ask) and whether you're signed up or on the waitlist. --past lists the events that were, the latest first, with a link to each write-up. --mine keeps only your own.

At a tasting you are at, events pours EVENT_ID lists what is poured, as the live page shows it: a blind wine stays hidden until it is out of its bag. notes add --pour POUR_ID --score 4.2 --note "..." writes your note of a pour, which takes its wine and day from the event; while the scores are open it is a draft, and its score counts toward the results when you take part and the pour is open (the command says when it didn't). A pour takes one note: to change yours, use notes edit.

If you host or speak at the tasting, events score EVENT_ID POUR_ID "Vika K" --score 4.2 gives a participant's score at a pour, with --favourite or --outcast, as the manage page does; --clear takes it out. Each run sets their whole row, so give the score and the sentiment together. Their score counts in the results, and makes them a note with no words if they have none.

You can run it from the command line too. events order EVENT_ID 1236 1234 1235 puts every pour in order, first poured first, as dragging them on the manage page does. events start EVENT_ID opens the live page and tells the members signed up for a seat. events reveal EVENT_ID shows the blind pours to the room, and events state EVENT_ID scoring (then scores_finalized) moves the event along. events edit EVENT_ID changes what the event is, where and when, and who may come: --title, --description-file notes.md (Markdown; - reads it from standard input), --date 2026-12-12T19:00+02:00 (the time with its offset from UTC: Kyiv is +02:00 in winter and +03:00 in summer), --place (as on a note: home, a venue's id, or your words), --seats, --registration open|supporters|closed, --visibility visible|hidden, --max-favourites and --max-outcasts; --clear date (or venue, seats, ...) empties one. More seats take the first in line, who are told. The rest of the manage page's flight and live controls (adding a pour, naming a placeholder, pouring a bottle of yours, opening or finishing a pour, showing the scores) is reachable with barberry api. Prices, extras, which pours the results count, moving an event back to a draft, the event's price, collection, payment link, speaker and tag, money, sign-ups and messages to the room stay on the site. Running a tasting needs a sign-in made with barberry 0.21.0 or later: run barberry login again, and type the code on the approval page, which asks for it before handing out a way to run your tastings.

events show gives an event in full, with a link to every write-up of it you may read (a report in another language or a follow-up shows next to the first), and once its scores are final, its results: each wine's weighted average and place, its favourites and outcasts, and your own score. Who scored what shows to whoever was there. Signing up happens on the event's page on the site.

Posts and producers

barberry posts list jura
barberry posts list --kind report --since 2026-01-01
barberry posts show SLUG
barberry producers list selosse
barberry producers show PRODUCER_ID
barberry wines list --producer PRODUCER_ID

posts list shows what Barberry published, the latest first: event reports, essays, interviews and site updates. Narrow it by words of the title, --tag, --kind, --event, --wine (a wine it names, or one poured at the event it reports on once its scores are final), --producer, --language and dates. --mine lists your own posts, drafts too.

posts show gives a post in full, by its slug or id: its text, and the wines, tasting notes, producers and posts it names. A report's score table comes from its event: events show gives the results.

producers list finds producers by name. producers show gives what Barberry wrote about one, where they make wine, how many of their wines the catalog has and their average score. wines list --producer and cellar list --producer list their wines.

Your ledger

barberry ledger
barberry ledger entries
barberry ledger entries --currency UAH --through-barberry --all
barberry ledger entries --settled-directly

ledger shows what you owe each host (below zero) or have with them as credit, one line per host and currency. Money settled directly with a host, such as a wine run, shows apart and is never added to what you owe through Barberry. For a host you owe through Barberry, it prints how they ask to be paid, and it gives the link to top up, with what a top-up would clear. Paying happens on the site.

ledger entries lists the rows, the latest first: each charge and payment, the balance it left with that host, and for an event's settlement what it charged for. --host, --currency, --settled-directly and --through-barberry narrow the list.

Places and grapes

barberry countries list
barberry regions list --country Italy
barberry appellations list --region Piedmont
barberry grapes list

When something goes wrong

The command line says what to do about it:

  • "can't reach api.barberry.io": no connection. Check it and run the command again. --verbose says what stood in the way.
  • "lost the connection ...; it may have gone through": a change was sent, and its answer never came back. It may have been made, so look (notes list, cellar list) before you run it again, or it may be made twice.
  • "this barberry is too old for the server": run brew upgrade barberry.
  • "this sign-in can't ...": your sign-in is from before the command line could do this. Run barberry login again.
  • "the server found nothing with that id": check the id (a list command finds it again), or run brew upgrade barberry if your build is old.
  • "the free allowance of API tokens is ...": without a membership, the command line works on a free allowance, and it is spent for now. The message says when to try again; a membership raises it.

Formats

Every list prints as a table at a terminal and as JSON lines in a pipe. --format picks one: table, json, jsonl or tsv (for a spreadsheet). In the JSON forms each wine and note is exactly what the API answers.

Ask an assistant

An assistant that runs commands, such as Claude Code, can use barberry for you. Teach it how first:

barberry skill install

It puts a skill in ~/.claude/skills/barberry: which command answers which question, what the answers hold, and that what it reads is yours. From its next session on, ask it things like "which Champagne do I have below 3000 UAH that I haven't tasted?" or "what did I score highest this year?", and it runs the commands itself. After brew upgrade barberry, the first command you run brings the skill up to date, so it always describes the commands you have. --dir puts it somewhere else, and barberry skill show prints it for an assistant that takes it another way.

For a question across everything at once, or an assistant that can't run commands, export it all:

barberry export --out barberry-export

It writes into the folder wines.jsonl (every wine you can see, what Barberry wrote of it, and your own score), notes.jsonl (your notes and Barberry's), cellar.jsonl (your bottles, when you keep a cellar here) and a README.md that says what the fields are. Hand the folder to an assistant and ask it which wines you love most, what they have in common, or what to try next.

The folder holds your private notes and what your bottles cost: keep it to yourself.

What it tells Barberry

After each command, the command line tells Barberry which command ran, the format it printed in, and whether it worked (barberry token tells nothing, so scripts calling it stay quick), and, when something failed that the server can't see (a lost connection, the keychain, files it couldn't write, an answer it couldn't read, a crash), what kind of failure it was, so it can be fixed. Never what you asked for: no search words, filters, wine names or file paths.

Which command ran counts only while "Share usage statistics" is on in your account, as on the site and in the app. DO_NOT_TRACK=1 stops both from that computer.

The command line - Barberry Garden