Mealie Cli

Mealie CLI

Every Mealie API endpoint, plus a local SQLite mirror that answers cross-recipe questions no other Mealie tool can: what you can cook now, this week's plan as one shopping list, and library-wide stats.

mealie wraps the full Mealie REST API as typed, agent-native commands, then syncs your recipes, meal plans, and shopping data into a local store. That local mirror powers offline full-text search and novel commands like cook-now, plan shopping-list, and stats that the API alone can't answer.

Install

Requires Go 1.26.4 or newer.

Go install

go install github.com/jez500/mealie-cli/cmd/mealie@latest
# optional MCP server binary:
go install github.com/jez500/mealie-cli/cmd/mealie-mcp@latest

Pre-built binary

Download a pre-built archive for your platform from the latest release. Each release ships darwin, linux, and windows builds for amd64 and arm64. On macOS, clear the Gatekeeper quarantine: xattr -d com.apple.quarantine mealie. On Unix, mark it executable: chmod +x mealie.

Build from source

git clone https://github.com/jez500/mealie-cli.git
cd mealie-cli
make build        # produces ./bin/mealie
make build-all    # also builds ./bin/mealie-mcp

Use with Claude Desktop (MCP)

The mealie-mcp binary mirrors every CLI command as an MCP tool. Install it and add it to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

go install github.com/jez500/mealie-cli/cmd/mealie-mcp@latest

{
  "mcpServers": {
    "mealie": {
      "command": "mealie-mcp",
      "env": {
        "MEALIE_BASE_URL": "https://recipes.example.com",
        "MEALIE_API_TOKEN": "<your-token>"
      }
    }
  }
}

Authentication

Create a long-lived API token in Mealie under Profile -> API Tokens, then set MEALIE_BASE_URL (your Mealie origin, e.g. https://recipes.example.com) and MEALIE_API_TOKEN. The CLI sends it as an Authorization: Bearer header.

Quick Start

# verify the CLI is wired before hitting the API
mealie doctor --dry-run

# mirror recipes, plans, and organizers into the local store
mealie sync

# instant offline full-text search over synced recipes
mealie search "soup"

# rank recipes by ingredients you already have
mealie cook-now --have eggs --have flour

# one consolidated shopping list for the week's plan
mealie plan shopping-list --days 7

Unique Features

These capabilities aren't available in any other tool for this API.

Local state that compounds

• cook-now — Rank your synced recipes by how much of their ingredient list you already have on hand.

  Reach for this when the user asks what they can cook from what they have, not for plain recipe search.

  mealie cook-now --have eggs --have flour --have butter --agent
  

• plan week — Show the upcoming week of planned meals from the local mirror, including empty days.

  Use for an at-a-glance week view; the raw mealplans endpoint returns an unordered flat list.

  mealie plan week --days 7 --agent
  

• plan shopping-list — Merge and dedupe ingredients across every recipe planned in a date window into one shopping list.

  Use to turn this week's plan into a single shopping run instead of one list per recipe.

  mealie plan shopping-list --days 7 --agent
  

Insight over the whole library

• stats — Counts, top tags/categories/foods, average rating, and missing-metadata coverage across your whole library.

  Use to summarize a recipe library at a glance before planning or cleanup.

  mealie stats --agent
  

• untagged — Find recipes missing a category, tag, or image so you can tidy your library.

  Use for library cleanup; pair with bulk tag/categorize to fix gaps.

  mealie untagged --missing tag --agent
  

Recipes

Import a recipe from a URL

mealie recipes parse-url --url https://example.com/best-brownies

Delegates to Mealie's built-in scraper and stores the parsed recipe.

Find recipes you can cook tonight

mealie cook-now --have chicken --have rice --have onion --json

Ranks synced recipes by how much of their ingredient list you already have.

Turn this week's plan into one shopping list

mealie plan shopping-list --days 7 --json

Merges and dedupes ingredients across every planned recipe.

Trim a verbose recipe payload for an agent

mealie recipes list --json --select items.name,items.slug,items.tags.name

Mealie recipe objects are large; --select keeps only the fields the agent needs.

Audit library metadata gaps

mealie untagged --missing tag --json

Lists recipes with no tags so you can bulk-fix them.

Usage

Run mealie --help for the full command reference and flag list.

Commands

admin

Manage admin

• mealie admin check-app-config - Check App Config
• mealie admin check-email-config - Get general application information
• mealie admin clean-images - Purges all the images from the filesystem that aren't .webp
• mealie admin clean-recipe-folders - Deletes all the recipe folders that don't have names that are valid UUIDs
• mealie admin clean-temp - Clean Temp
• mealie admin create - Create One
• mealie admin create-groups - Create One
• mealie admin create-groups-2 - Create Ai Provider
• mealie admin create-households - Create One
• mealie admin create-users - Create One
• mealie admin debug-openai - Debug Openai
• mealie admin delete - Delete One
• mealie admin delete-groups - Delete One
• mealie admin delete-groups-2 - Delete Ai Provider
• mealie admin delete-households - Delete One
• mealie admin delete-users - Delete One
• mealie admin generate-token - Generates a reset token and returns it. This is an authenticated endpoint
• mealie admin get-ai-provider - Get Ai Provider
• mealie admin get-all - Get All
• mealie admin get-all-groups - Get All
• mealie admin get-all-households - Get All
• mealie admin get-all-users - Get All
• mealie admin get-app-info - Get general application information
• mealie admin get-app-statistics - Get App Statistics
• mealie admin get-maintenance-summary - Get the maintenance summary
• mealie admin get-one - Returns a token to download a file
• mealie admin get-one-groups - Get One
• mealie admin get-one-households - Get One
• mealie admin get-one-users - Get One
• mealie admin get-storage-details - Get Storage Details
• mealie admin import-one - Import One
• mealie admin send-test-email - Send Test Email
• mealie admin unlock-users - Unlock Users
• mealie admin update - Update One
• mealie admin update-groups - Update Ai Provider
• mealie admin update-households - Update One
• mealie admin update-users - Update One
• mealie admin upload-one - Upload a .zip File to later be imported into Mealie

app

Manage app

• mealie app get-info - Get general application information
• mealie app get-startup-info - returns helpful startup information
• mealie app get-theme - Get's the current theme settings

comments

Manage comments

• mealie comments create - Create One
• mealie comments delete - Delete One
• mealie comments get-all - Get All
• mealie comments get-one - Get One
• mealie comments update - Update One

explore

Manage explore

• mealie explore get-all - Get All
• mealie explore get-all-groups - Get All
• mealie explore get-all-groups-2 - Get All
• mealie explore get-all-groups-3 - Get All
• mealie explore get-all-groups-4 - Get All
• mealie explore get-all-groups-5 - Get All
• mealie explore get-all-groups-6 - Get All
• mealie explore get-household - Get Household
• mealie explore get-one - Get One
• mealie explore get-one-groups - Get One
• mealie explore get-one-groups-2 - Get One
• mealie explore get-one-groups-3 - Get One
• mealie explore get-one-groups-4 - Get One
• mealie explore get-recipe - Get Recipe
• mealie explore suggest-recipes - Suggest Recipes

foods

Manage foods

• mealie foods create - Create One
• mealie foods delete - Delete One
• mealie foods get-all - Get All
• mealie foods get-one - Get One
• mealie foods merge-one - Merge One
• mealie foods update - Update One

groups

Manage groups

• mealie groups create - Create One
• mealie groups create-aiproviders - Create Ai Provider
• mealie groups delete - Delete One
• mealie groups delete-aiproviders - Delete Ai Provider
• mealie groups delete-reports - Delete One
• mealie groups get-ai-provider - Get Ai Provider
• mealie groups get-ai-provider-settings - Get Ai Provider Settings
• mealie groups get-all - Get All
• mealie groups get-all-households - Get All Households
• mealie groups get-all-reports - Get All
• mealie groups get-logged-in-user - Returns the Group Data for the Current User
• mealie groups get-member - Returns a single user belonging to the current group
• mealie groups get-members - Returns all users belonging to the current group
• mealie groups get-one - Get One
• mealie groups get-one-household - Get One Household
• mealie groups get-one-reports - Get One
• mealie groups get-preferences - Get Group Preferences
• mealie groups get-storage - Get Storage
• mealie groups seed-foods - Seed Foods
• mealie groups seed-labels - Seed Labels
• mealie groups seed-units - Seed Units
• mealie groups start-data-migration - Start Data Migration
• mealie groups update - Update Group Preferences
• mealie groups update-aiproviders - Update Ai Provider Settings
• mealie groups update-aiproviders-2 - Update Ai Provider
• mealie groups update-labels - Update One

households

Manage households

• mealie households add-recipe-ingredients-to-list - Add Recipe Ingredients To List
• mealie households add-single-recipe-ingredients-to-list - Add Single Recipe Ingredients To List
• mealie households create - Create One
• mealie households create-events - Create One
• mealie households create-invitations - Create Invite Token
• mealie households create-mealplans - Create One
• mealie households create-mealplans-2 - create_random_meal is a route that provides the randomized functionality for mealplaners. It operates by following the rules set out in the household's mealplan settings. If no settings are set, it will return any random meal.

Refer to the mealplan settings routes for more information on how rules can be applied to the random meal selector.

• mealie households create-mealplans-3 - Create One
• mealie households create-recipeactions - Create One
• mealie households create-shopping - Create One
• mealie households create-shopping-2 - Create One
• mealie households create-shopping-3 - Create Many
• mealie households create-webhooks - Create One
• mealie households delete - Delete One
• mealie households delete-events - Delete One
• mealie households delete-mealplans - Delete One
• mealie households delete-mealplans-2 - Delete One
• mealie households delete-recipeactions - Delete One
• mealie households delete-shopping - Delete Many
• mealie households delete-shopping-2 - Delete One
• mealie households delete-shopping-3 - Delete One
• mealie households delete-webhooks - Delete One
• mealie households email-invitation - Email Invitation
• mealie households get-all - Get All
• mealie households get-all-events - Get All
• mealie households get-all-mealplans - Get All
• mealie households get-all-mealplans-2 - Get All
• mealie households get-all-recipeactions - Get All
• mealie households get-all-shopping - Get All
• mealie households get-all-shopping-2 - Get All
• mealie households get-all-webhooks - Get All
• mealie households get-invite-tokens - Get Invite Tokens
• mealie households get-logged-in-user - Returns the Household Data for the Current User
• mealie households get-members - Returns all users belonging to the current household
• mealie households get-one - Get One
• mealie households get-one-events - Get One
• mealie households get-one-mealplans - Get One
• mealie households get-one-mealplans-2 - Get One
• mealie households get-one-recipeactions - Get One
• mealie households get-one-shopping - Get One
• mealie households get-one-shopping-2 - Get One
• mealie households get-one-webhooks - Get One
• mealie households get-preferences - Get Household Preferences
• mealie households get-recipe - Returns recipe data for the current household
• mealie households get-statistics - Get Statistics
• mealie households get-todays-meals - Get Todays Meals
• mealie households remove-recipe-ingredients-from-list - Remove Recipe Ingredients From List
• mealie households rerun-webhooks - Manually re-fires all previously scheduled webhooks for today
• mealie households set-member-permissions - Set Member Permissions
• mealie households test-notification - Test Notification
• mealie households test-one - Test One
• mealie households trigger-action - Trigger Action
• mealie households update - Update Many
• mealie households update-cookbooks - Update One
• mealie households update-events - Update One
• mealie households update-mealplans - Update One
• mealie households update-mealplans-2 - Update One
• mealie households update-preferences - Update Household Preferences
• mealie households update-recipeactions - Update One
• mealie households update-shopping - Update Many
• mealie households update-shopping-2 - Update One
• mealie households update-shopping-3 - Update One
• mealie households update-shopping-4 - Update Label Settings
• mealie households update-webhooks - Update One

mealie-auth

Manage mealie auth

• mealie mealie-auth get-token - Get Token
• mealie mealie-auth logout - Logout
• mealie mealie-auth oauth-callback - Oauth Callback
• mealie mealie-auth oauth-login - Oauth Login
• mealie mealie-auth refresh-token - Use a valid token to get another token

media

Manage media

• mealie media get-recipe-asset - Returns a recipe asset
• mealie media get-recipe-img - Takes in a recipe id, returns the static image. This route is proxied in the docker image and should not hit the API in production
• mealie media get-recipe-timeline-event-img - Takes in a recipe id and event timeline id, returns the static image. This route is proxied in the docker image and should not hit the API in production
• mealie media get-user-image - Takes in a recipe slug, returns the static image. This route is proxied in the docker image and should not hit the API in production
• mealie media get-validation-text - Get Validation Text

organizers

Manage organizers

• mealie organizers create - Creates a Category in the database
• mealie organizers create-tags - Creates a Tag in the database
• mealie organizers create-tools - Create One
• mealie organizers delete - Removes a recipe category from the database. Deleting a category does not impact a recipe. The category will be removed from any recipes that contain it
• mealie organizers delete-tags - Removes a recipe tag from the database. Deleting a tag does not impact a recipe. The tag will be removed from any recipes that contain it
• mealie organizers delete-tools - Delete One
• mealie organizers get-all - Returns a list of available categories in the database
• mealie organizers get-all-empty - Returns a list of categories that do not contain any recipes
• mealie organizers get-all-tags - Returns a list of available tags in the database
• mealie organizers get-all-tools - Get All
• mealie organizers get-empty-tags - Returns a list of tags that do not contain any recipes
• mealie organizers get-one - Returns a list of recipes associated with the provided category.
• mealie organizers get-one-by-slug - Returns a category object with the associated recieps relating to the category
• mealie organizers get-one-by-slug-tags - Get One By Slug
• mealie organizers get-one-by-slug-tools - Get One By Slug
• mealie organizers get-one-tags - Returns a list of recipes associated with the provided tag.
• mealie organizers get-one-tools - Get One
• mealie organizers update - Updates an existing Tag in the database
• mealie organizers update-tags - Updates an existing Tag in the database
• mealie organizers update-tools - Update One

parser

Manage parser

• mealie parser parse-ingredient - Parse Ingredient
• mealie parser parse-ingredients - Parse Ingredients

recipes

Manage recipes

• mealie recipes bulk-categorize - Bulk Categorize Recipes
• mealie recipes bulk-delete - Bulk Delete Recipes
• mealie recipes bulk-export - Bulk Export Recipes
• mealie recipes bulk-settings - Bulk Settings Recipes
• mealie recipes bulk-tag - Bulk Tag Recipes
• mealie recipes create - Takes in a JSON string and loads data into the database as a new entry
• mealie recipes create-create - Takes in raw HTML or a https://schema.org/Recipe object as a JSON string and parses it like a URL
• mealie recipes create-create-2 - Create a recipe from an image using OpenAI. Optionally specify a language for it to translate the recipe to.
• mealie recipes create-create-3 - Create recipe from archive
• mealie recipes create-create-4 - Takes in raw HTML or a https://schema.org/Recipe object as a JSON string and parses it like a URL, streaming progress via SSE
• mealie recipes create-timeline - Create One
• mealie recipes delete - Deletes a recipe by slug
• mealie recipes delete-timeline - Delete One
• mealie recipes get-all - Get All
• mealie recipes get-all-timeline - Get All
• mealie recipes get-exported-data - Get Exported Data
• mealie recipes get-exported-data-token - Returns a token to download a file
• mealie recipes get-formats-and-templates - Get Recipe Formats And Templates
• mealie recipes get-one - Takes in a recipe's slug or id and returns all data for a recipe
• mealie recipes get-one-timeline - Get One
• mealie recipes get-shared - Get Shared Recipe
• mealie recipes get-shared-as-zip - Get a recipe and its original image as a Zip file
• mealie recipes parse-url - Takes in a URL and attempts to scrape data and load it into the database
• mealie recipes parse-url-bulk - Takes in a URL and attempts to scrape data and load it into the database
• mealie recipes parse-url-stream - Takes in a URL and attempts to scrape data and load it into the database, streaming progress via SSE
• mealie recipes patch-many - Patch Many
• mealie recipes patch-one - Updates a recipe by existing slug and data.
• mealie recipes purge-export-data - Remove all exports data, including items on disk without database entry
• mealie recipes suggest - Suggest Recipes
• mealie recipes test-parse-url - Test Parse Recipe Url
• mealie recipes update - Update Many
• mealie recipes update-slug - Updates a recipe by existing slug and data.
• mealie recipes update-timeline - Update One
• mealie recipes update-timeline-2 - Update Event Image

shared

Manage shared

• mealie shared create - Create One
• mealie shared delete - Delete One
• mealie shared get-all - Get All
• mealie shared get-one - Get One

units

Manage units

• mealie units create - Create One
• mealie units delete - Delete One
• mealie units get-all - Get All
• mealie units get-one - Get One
• mealie units merge-one - Merge One
• mealie units update - Update One

users

Manage users

• mealie users create - Create api_token in the Database
• mealie users delete - Delete api_token from the Database
• mealie users forgot-password - Sends an email with a reset link to the user
• mealie users get-logged-in - Get Logged In User
• mealie users get-logged-in-favorites - Get Logged In User Favorites
• mealie users get-logged-in-rating-for-recipe - Get Logged In User Rating For Recipe
• mealie users get-logged-in-ratings - Get Logged In User Ratings
• mealie users register-new - Register New User
• mealie users reset-password - Resets the user password
• mealie users update - Resets the User Password
• mealie users update-itemid - Update User

utils

Manage utils

• mealie utils - Uses a file token obtained by an active user to retrieve a file from the operating system.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
mealie admin check-app-config

# JSON for scripting and agents
mealie admin check-app-config --json

# Filter to specific fields
mealie admin check-app-config --json --select id,name,status

# Dry run — show the request without sending
mealie admin check-app-config --dry-run

# Agent mode — JSON + compact + no prompts in one flag
mealie admin check-app-config --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Explicit retries - add --idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
• Confirmable - --yes for explicit confirmation of destructive actions
• Piped input - write commands can accept structured input when their help lists --stdin
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

mealie doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/mealie/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, mealie doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run mealie doctor to check credentials
• Verify the environment variable is set: echo $MEALIE_API_TOKEN Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• 401 Unauthorized on every call — Confirm MEALIE_API_TOKEN is a long-lived token from Profile -> API Tokens and MEALIE_BASE_URL has no trailing /api.
• cook-now or stats returns nothing — Run mealie sync first; transcendence commands read the local mirror.
• connection refused / DNS error — Check MEALIE_BASE_URL points at the reachable Mealie origin; run mealie doctor.

Sources & Inspiration

This CLI was built by studying these projects and resources:

• rldiao/mealie-mcp-server — Python
• mdlopresti/mealie-mcp — Python
• counterbeing/mealie-mcp-ts — TypeScript
• GrandMoff100/MealieAPI — Python

Generated by CLI Printing Press