flavornotes

Log, search, and export your coffee tasting notes from the terminal.

A companion CLI for Flavor Notes. All your raw tasting data, accessible anywhere you have a shell.

npm install -g flavornotes

Requires Node.js 18+.

Setup

1. Get a CLI token

Open the Flavor Notes app, go to Settings, and generate a CLI token.

2. Authenticate

flavornotes auth login --token <your-token>

3. (Optional) Set an AI key for natural language input

flavornotes config set api-key sk-...
flavornotes config set model claude   # claude | gemini | openai

Without an AI key, all structured flag commands still work. Natural language input requires a key.

Quick start

# Log a note in plain English
flavornotes log "just had an incredible Ethiopian from Onyx, jasmine finish, 4.5 stars"

# See what you've logged recently
flavornotes last 5

# Search your notes
flavornotes search "best pour over I had this year"

# Export everything
flavornotes export --format csv --out ~/coffee-notes.csv

Commands

Auth

flavornotes auth login --token <token>   # authenticate
flavornotes auth status                  # check login status
flavornotes auth logout                  # remove stored token

Logging

# Natural language (confirms before saving)
flavornotes log "Ethiopia Natural from Onyx, blueberry, jasmine, 4 stars"

# Explicit flags
flavornotes log --coffee "Ethiopia Natural" --roaster "Onyx" --method v60 --flavors "blueberry,jasmine" --rating 4

# For scripts and agents (skips confirmation, returns JSON)
flavornotes log --coffee "Ethiopia Natural" --rating 4 --json

Available log flags: --coffee --roaster --origin --method --flavors --rating --notes --roast --dose --water --temp --time --grind

Reading notes

flavornotes last              # 5 most recent notes
flavornotes last 10           # adjust count
flavornotes last --method v60 # filter by brew method
flavornotes last --bean "Onyx Ethiopia"

flavornotes search "every V60 I rated above 4 stars"
flavornotes search "that nutty medium roast I loved last fall"
flavornotes search "best Ethiopian I had this year"

flavornotes favorites
flavornotes favorites --method espresso

Editing

flavornotes edit <id> --rating 5 --notes "Even better cold"
flavornotes edit <id> --favorite

Stats

flavornotes stats
# 49 tastings logged · 20 roasters · 14 origins · streak: 4 days

Returns: total notes, unique roasters, unique origins, current streak. No computed insights.

Recipes and equipment

flavornotes recipes
flavornotes recipes --have "french press, gooseneck kettle"

flavornotes equipment
flavornotes equipment add --name "Morning Kit" --grinder "Comandante C40" --dripper "Kalita Wave"

Export and import

flavornotes export                            # JSON (default)
flavornotes export --format csv
flavornotes export --format obsidian          # Obsidian-compatible markdown files
flavornotes export --since 30d
flavornotes export --since 2024-01-01
flavornotes export --out ~/Desktop/notes.csv

flavornotes import ~/flavornotes-backup.json
flavornotes import ~/flavornotes-backup.json --dry-run
flavornotes import ~/flavornotes-backup.json --skip-dupes

Export schema per entry: id, coffee_name, roaster, origin, process, roast_level, roast_date, brew_method, grind_size, dose_grams, water_grams, water_temp, brew_time_seconds, flavors, rating, acidity, sweetness, body, bitterness, aftertaste, notes, is_favourite, recipe_name, created_at, fn_url

Account

flavornotes account

JSON output

Every command supports --json for structured output. Useful for scripts, agents, and pipes.

flavornotes last 5 --json
flavornotes stats --json
flavornotes search "fruity light roasts" --json
flavornotes export --format json --since 7d

Natural language input

Any command accepts a plain English description instead of flags. The CLI parses your intent, shows you what it understood, and asks for confirmation before saving.

$ flavornotes log "just had the most incredible Ethiopian from Onyx, jasmine finish, give it a 4.5"

Got it. Logging:
  Coffee: Ethiopia Natural · Roaster: Onyx Coffee Lab
  Brew method: not specified · Flavors: jasmine · Rating: 4.5★

Save this note? (y/n)

The AI layer supports Claude (default), Gemini, and OpenAI. Configure in ~/.config/flavornotes/config.json, or per command with --model claude|gemini|openai.

What stays in the app

The CLI returns your raw input data only. The following are computed by Flavor Notes and are not available via CLI or export:

• Flavor signature scores
• Palate type
• Flavor correlation analysis
• Palate uniqueness score
• Community comparison data
• Monthly story narrative

Full insights are at flavornotes.app.

Configuration

Stored in ~/.config/flavornotes/config.json:

{
  "model": "claude",
  "api_key": "sk-..."
}

Credentials are stored in ~/.config/flavornotes/credentials with chmod 600.

License

MIT