Getting Started & Help

Getting Started

Prerequisites

Before installing CookBot, ensure you have:

1. A Cook.md account with an active AI subscription
2. A terminal that supports modern ANSI escape sequences
3. A recipes directory (or create one to start fresh)

Installation

macOS (Homebrew)

brew install cook-md/tap/cookbot

First Run

1. Start CookBot with your recipes directory:

   cookbot ~/my-recipes

   Or run from within your recipes directory:

   cd ~/my-recipes
   cookbot

2. Authenticate: On first launch, CookBot will prompt you to login via your browser.
3. Start chatting: Once authenticated, type a message and press Enter to start interacting with the AI assistant.

Quick Start Example

After launching CookBot, try these starter prompts:

Troubleshooting

Connection Issues

Problem: "Failed to connect to gRPC server"

This means the CookBot backend server is not accessible.

Solutions:

1. Check your internet connection
2. Verify the server URL is correct
3. Try again in a few moments (temporary outage)
4. Check if a firewall is blocking the connection

Problem: "Session expired"

Your authentication token has expired.

Solution: Run /login to re-authenticate.

Authentication Issues

Problem: Login page doesn't open

Solutions:

1. Manually visit the URL shown in the terminal
2. Check your default browser settings
3. Try a different browser

Problem: "Subscription required"

You need an active AI subscription to use CookBot.

Solution: Press Enter to open the subscription page, or visit cook.md to subscribe.

Display Issues

Problem: Garbled or broken characters

Your terminal may not support the required features.

Solutions:

1. Use a modern terminal (iTerm2, Alacritty, Windows Terminal)
2. Ensure your terminal uses a Unicode-compatible font
3. Check that your TERM environment variable is set correctly

Problem: Colors not displaying correctly

Solutions:

1. Ensure your terminal supports 256 colors or TrueColor
2. Check the terminal's color scheme settings

File Operation Issues

Problem: "Path not found" errors

Solutions:

1. Verify the recipes directory exists
2. Check file permissions
3. Use relative paths from the recipes directory
4. Avoid using .. in paths (not allowed for security)

Problem: Recipe not parsing correctly

Solutions:

1. Check Cooklang syntax (ingredients use @, cookware uses #, timers use ~)
2. Ensure metadata block has proper --- delimiters
3. Look for unclosed brackets or quotes

Performance Issues

Problem: Slow responses

Solutions:

1. Check your internet connection speed
2. Complex queries may take longer to process
3. Use /compact to reduce context size in long conversations

Problem: High token usage

Solutions:

1. Use /clear to start a fresh conversation
2. Use /compact to summarize and reduce context
3. Be more specific in your queries to reduce back-and-forth

Still Having Issues?

If you can't resolve your issue with the steps above:

• Use the /feedback command in CookBot to report the problem
• Open an issue on GitHub

When reporting, please include:

• CookBot version (/version)
• Operating system
• Steps to reproduce the issue
• Relevant logs from ~/.cookbot/logs/

FAQ

General Questions

Q: Is CookBot free?

A: CookBot requires a Cook.md account with an AI subscription ($12/month) to use the AI features.

Q: Are my recipes sent to the cloud?

A: No. Your recipe files stay on your local machine. Only your queries and the content you explicitly ask about are sent to the AI service for processing. The conversation is processed on secure servers and not stored permanently.

Q: What file formats does CookBot support?

A: CookBot works primarily with Cooklang files (.cook) and menu files (.menu). It can also read and write other text files like .txt and .md within your recipes directory.

Q: Can I use CookBot offline?

A: No, CookBot requires an internet connection to communicate with the AI backend and authentication services.

Cooklang Questions

Q: What is Cooklang?

A: Cooklang is a markup language for writing recipes in plain text. It uses simple syntax like @ingredient{amount%unit} for ingredients, #cookware{} for tools, and ~{time%unit} for timers. Learn more at cooklang.org.

Q: How do I reference another recipe?

A: Use the path syntax: @./path/to/recipe{servings}. For example, @./sauces/bechamel{2} references the bechamel recipe scaled to 2 servings.

Q: What metadata should I include?

A: Common metadata includes:

• servings - Number of portions
• time - Total cooking time
• tags - Comma-separated categories
• source - Where the recipe came from

Feature Questions

Q: Can CookBot generate images?

A: No, CookBot is a text-based interface focused on recipe management and does not generate images.

Q: Can I export my conversation?

A: Yes! Use /save or /save filename.md to save your conversation as a Markdown file.

Q: How does the shopping cart work?

A: The cart aggregates ingredients from recipes you add. Use /cart add recipe.cook to add recipes, and /cart to see the combined list. It merges quantities for the same ingredient across recipes.

Q: Can CookBot scale recipes automatically?

A: Yes! Use the :scale suffix when viewing or adding recipes. For example, /recipe pasta.cook:2 shows the recipe doubled, and /cart add soup.cook:0.5 adds half portions to your cart.

Technical Questions

Q: Where are my settings stored?

A: Settings are stored in ~/.cookbot/settings.json. Authentication is stored in ~/.cookbot/auth.json.

Q: How do I update CookBot?

A: CookBot checks for updates automatically on launch. You can also run cookbot --update to check manually. For Homebrew installations, use brew upgrade cookbot.

Q: Can I self-host the backend?

A: The backend requires access to AI services and is currently only available as a hosted service through Cook.md.

Q: How do I report bugs or give feedback?

A: You can report issues and suggest features in two ways:

• Use the /feedback command directly in CookBot
• Open an issue on GitHub

Cooklang Quick Reference

Ingredients

@salt                       -- Simple ingredient
@salt{1%tsp}               -- With quantity and unit
@chicken breast{500%g}     -- Multi-word ingredient
@butter{=50%g}             -- Fixed (doesn't scale)
@onion{1}(diced)           -- With preparation note

Cookware

#pot                       -- Simple cookware
#baking sheet{}            -- Multi-word cookware
#cast iron skillet{large}  -- With description

Timers

~{25%minutes}              -- Unnamed timer
~pasta{10%min}             -- Named timer

Metadata (YAML frontmatter)

---
title: Spaghetti Carbonara
servings: 4
time: 30 minutes
tags: [pasta, quick, italian]
---

Menu Files

[Monday]
Soups/tomato-soup.cook:2
Breads/focaccia.cook

[Tuesday]
Pasta/carbonara.cook
Salads/caesar.cook