Skip to main content

​
Quickstart Guide

This guide walks you through launching toni, completing the onboarding flow, and logging your first restaurant visit.

​
Launch toni

1

Start the Application

Open your terminal and run:
toni
On first launch, you’ll see the onboarding screen.
2

Complete Onboarding (First Run Only)

toni will ask if you want to enable Yelp API for restaurant autocomplete.Option 1: Enable Yelp Autocomplete (Recommended)
  1. Press y or ↓ to select “Enable YELP autocomplete”
  2. Press Enter to confirm
  3. You’ll be prompted to enter your API key:
Option 2: Skip Yelp Setup (Offline Mode)
  1. Press n or ↓ to select “Disable YELP autocomplete”
  2. Press Enter to confirm
  3. toni works perfectly offline—you’ll just type restaurant names manually
Yelp’s free tier provides 10,000 API calls per month with no credit card required. The autocomplete saves time by filling in restaurant details automatically.
3

Explore the Three Main Screens

After onboarding, you’ll land on the Visits screen. toni has three main tabs:Visits - Your dining history (starts empty)Want to Visit - Your restaurant wishlistRestaurants - All restaurants you’ve loggedNavigate between tabs using:
  • b / f - Previous / next tab
  • r - Jump to Restaurants
  • w - Jump to Want to Visit
  • v - Jump to Visits

​
Log Your First Visit

1

Press 'a' to Add a Visit

From the Visits screen, press a to open the visit form.You’ll see a form with these fields:
  • Restaurant name (required)
  • Date visited (defaults to today)
  • Rating (1-10 scale)
  • Would you return? (Yes/No)
  • Notes (free text)
2

Fill in Restaurant Details

With Yelp API Enabled:
  1. Start typing a restaurant name (at least 2 characters)
  2. Autocomplete suggestions appear below
  3. Use j/k or ↓/↑ to navigate suggestions
  4. Press Tab or Enter to select
  5. Restaurant details (city, cuisine) auto-fill
Without Yelp API:
  1. Type the restaurant name manually
  2. Press Tab to move to the next field
  3. Fill in city, cuisine, price range manually
The restaurant field supports autocomplete when you type 2+ characters. Press Esc to dismiss the dropdown if needed.
3

Add Visit Details

Press Tab to move between fields:Date - Format: YYYY-MM-DD (defaults to today)
2026-03-04
Rating - 1-10 scale (optional)
8.5
Would Return? - Type y, yes, n, or no (optional)
yes
Notes - Free text for your thoughts (optional)
Amazing pasta carbonara. Service was slow but food made up for it.
Use Shift+Tab to move to the previous field if you need to go back.
4

Save Your Visit

Press Ctrl+S to save the visit.You’ll return to the Visits screen and see your entry in the table.Press Esc anytime to cancel without saving.

​
Essential Keybindings

From internal/ui/keys.go:48-171:
KeyAction
j / ↓Move down
k / ↑Move up
h / ← / escGo back
l / → / enterOpen / select
ggJump to top
GJump to bottom
ctrl+dHalf page down
ctrl+uHalf page up
?Toggle help
qQuit

​
Visits Screen

KeyAction
aAdd new visit
rGo to Restaurants
wGo to Want to Visit
enterOpen visit details
b / fPrevious / next tab

​
Restaurants Screen

KeyAction
aAdd restaurant
vLog visit for selected restaurant
enterOpen restaurant details
hBack to Visits

​
Want to Visit Screen

KeyAction
aAdd place to wishlist
enterOpen details
cMark as visited (converts to visit)
vGo to Visits
rGo to Restaurants

​
Detail Screens

KeyAction
h / escBack to list
eEdit entry
dDelete entry
vAdd visit (from restaurant detail)

​
Insert/Edit Mode (Forms)

KeyAction
TabNext field
Shift+TabPrevious field
Ctrl+SSave
EscCancel
When in autocomplete mode (Yelp API enabled), use j/k or arrow keys to navigate suggestions, then Tab or Enter to select. Press Esc to dismiss the dropdown.

​
Advanced Navigation

​
Table Controls

From the Visits or Restaurants screen:
KeyAction
tabNext column
shift+tabPrevious column
/ then 1-9Jump to specific column
sCycle sort (none → asc → desc → none)
cHide active column
CShow all columns
nFilter by selected cell value
NClear filter

​
Undo/Redo

From internal/ui/keys.go:162-169:
KeyAction
uUndo last action
Ctrl+RRedo
Press ? anytime to see the full help screen with all available keybindings.

​
Example Workflow

Here’s a typical workflow for tracking a restaurant visit: 
# 1. Launch toni
toni

# 2. Press 'a' from Visits screen
# 3. Type restaurant name: "Roberta's"
# 4. Select from autocomplete (if enabled)
# 5. Tab to date field (defaults to today)
# 6. Tab to rating: "9"
# 7. Tab to would return: "yes"
# 8. Tab to notes: "Best wood-fired pizza in Brooklyn"
# 9. Ctrl+S to save

​
Troubleshooting

​
Terminal Too Small

If you see “Terminal too small”, toni requires at least 72x18 characters. Resize your terminal or reduce font size.

​
Yelp API Not Working

From main.go:26-34, if Yelp autocomplete isn’t working:
  1. Check that your API key is set: 
    cat ~/.toni/yelp_api_key
  2. Verify the key is valid at https://www.yelp.com/developers/v3/manage_app
  3. Re-run onboarding by deleting the config: 
    rm ~/.toni/onboarding.json
toni

​
Database Issues

If toni won’t start due to database errors: 
# Backup your database first
cp ~/.toni/toni.db ~/.toni/toni.db.backup

# Try opening with sqlite3 to check integrity
sqlite3 ~/.toni/toni.db "PRAGMA integrity_check;"

​
Next Steps

Now that you’ve logged your first visit, explore more features:
  • Use the Restaurants screen to see aggregate stats and visit history
  • Build a wishlist in Want to Visit for places you want to try
  • Press ? to see the full help screen with all keybindings
  • Sort and filter tables with s and n for powerful data exploration

Full Documentation

Learn about all features, data model, and advanced usage

Build docs developers (and LLMs) love

Get started for freeTalk to us