---
title: "Command line — Tiny Plates recipe API"
description: "Search recipes, cook from your pantry and build shopping lists from the terminal with the tiny-plates command. Sign in with your browser or use an API key."
url: "https://www.tinyplates.dev/docs/cli"
---

# Command line

The tiny-plates command lets you search recipes, cook from your pantry and build shopping lists without leaving the terminal. It can do everything the API can.

## Run it

The command comes with the [tiny-plates package](https://www.npmjs.com/package/tiny-plates) and needs Node 20 or later. Run it with `npx`, without installing anything:

```
$ npx tiny-plates search carbonara --limit 2
1. Spaghetti Carbonara Recipe
   Italian · Dinner · 30 min · Serves 4 · ★ 4.8 (58)
   69e234f8d0295ac8a90122c0

2. Brussels Sprouts Carbonara
   American · Dinner · 25 min · Serves 6 · ★ 5.0 (9)
   69e22e8ed0295ac8a9011fef

Run tiny-plates recipe <id> to see a recipe.
```

Lists show the title, a line about the recipe and its id. Pass the id to `recipe` to see the whole thing. If you use it a lot, install it once:

```
npm install --global tiny-plates
```

## Sign in

Run `tiny-plates login`. It opens Tiny Plates in your browser, and once you sign in the command saves the sign-in and renews it by itself. If the browser does not open, it prints the link for you. Requests count against your account’s [limits](https://www.tinyplates.dev/docs/rate-limits), the same as your API keys.

In scripts and CI, use an [API key](https://www.tinyplates.dev/docs/authentication) instead. Set `TINY_PLATES_API_KEY` or pass `--api-key`. A key wins over a saved sign-in.

## Examples

```
tiny-plates search chocolate cake --without eggs --limit 5
tiny-plates recipe carbonara --servings 4 --units metric
tiny-plates pantry egg tomato onion --max-missing 1 --without milk
tiny-plates shopping-list carbonara:4 caesar-salad
tiny-plates substitutions buttermilk
tiny-plates recipes --cuisine italian --diet vegetarian --max-total-minutes 30
```

Flags that take a list, like `--without`, take comma-separated values or the flag more than once. `tiny-plates vocabularies` lists the values that `--cuisine`, `--diet` and `--without` accept.

## Commands

* `login`Sign in in your browser.
* `logout`Sign out and forget the saved sign-in.
* `search <query>`Search recipes by text.
* `popular`The most popular recipes.
* `recipe <id>`One recipe, with its ingredients and steps.
* `recipes`Filter every recipe by cuisine, diet, time and more. Business plan only.
* `pantry <ingredients...>`Recipes ranked by how much your pantry covers.
* `shopping-list <recipes...>`One shopping list for several recipes, grouped by aisle.
* `substitutions <ingredients...>`What to use instead of an ingredient.
* `resolve <names...>`Ingredient names, in any language, to ids.
* `ingredient <id>`One ingredient.
* `pairings <id>`Ingredients that go well with this one.
* `ingredients`Every ingredient. Business plan only.
* `vocabularies`The values the filter flags accept.
* `status`How many recipes and sites there are.
* `health`Whether the API is up. Needs no key.

Every command takes `--api-key` and `--json`. Run `tiny-plates <command> --help` for its flags, with examples. The [README](https://github.com/Artmann/tiny-plates-js) lists them all.

## JSON output

Add `--json` to print the API response as JSON instead, for example to pipe it into `jq`:

```
tiny-plates search carbonara --json | jq '.results[].title'
```

In a terminal the command uses colours and shows a spinner. When you pipe it, or set `NO_COLOR`, it prints plain text. When a request fails, it says what went wrong and what to do, and exits with status 1.