# Inventory commands

> Manage your green coffee inventory.

HTML version: https://www.purveyors.io/docs/cli/inventory

Manage the green coffee inventory you see on the Beans page of the web app. Inventory IDs are separate from catalog IDs; roast and tasting commands expect inventory IDs.

Access: Member. Requires member access on your account.

## Before you start

> **Use inventory IDs for roast work**
>
> purvey roast --coffee-id expects an inventory ID from purvey inventory list, not a catalog ID.

## purvey inventory list

List your green coffee inventory with catalog details.

Usage: `purvey inventory list [options]`

Access: Member. Requires member access on your account.

- Returns your inventory items with their catalog details.
- The returned id field is the inventory ID, distinct from catalog_id.
- --offset + --limit enables pagination through large result sets.

| Argument or flag | Details |
| --- | --- |
| `--stocked` | Only coffees you have marked as in stock. |
| `--catalog-id <id>` | Only inventory items bought from this catalog coffee (a catalog ID). |
| `--purchase-date-start <YYYY-MM-DD>` | Only purchases made on or after this date. |
| `--purchase-date-end <YYYY-MM-DD>` | Only purchases made on or before this date. |
| `--origin <country>` | Only coffees whose country of origin contains this text. |
| `--limit <n>` | Maximum number of items to return. Default: 20. |
| `--offset <n>` | Number of items to skip when paging. Default: 0. |

Examples:

```bash
purvey inventory list --stocked --pretty
purvey inventory list --limit 20 --offset 20
```

## purvey inventory get

Get a single inventory item.

Usage: `purvey inventory get <id>`

Access: Member. Requires member access on your account.

| Argument or flag | Details |
| --- | --- |
| `<id>` | Required: Inventory ID of the item. |

Examples:

```bash
purvey inventory get 7 --pretty
```

## purvey inventory add

Add a bean to your inventory.

Usage: `purvey inventory add [options]`

Access: Member. Requires member access on your account.

- Flag mode requires --qty and exactly one of --catalog-id or --manual-name.
- --manual-name creates a manual coffee record when manual inventory entries are enabled.

| Argument or flag | Details |
| --- | --- |
| `--catalog-id <id>` | Catalog ID of the coffee you bought; use exactly one of --catalog-id or --manual-name. |
| `--manual-name <name>` | Name for a coffee that is not in the catalog; use exactly one of --catalog-id or --manual-name. |
| `--qty <lbs>` | Quantity purchased, in pounds. Required unless you use --form. |
| `--cost <dollars>` | Total amount paid for the beans, in US dollars (not the price per pound). |
| `--tax-ship <dollars>` | Tax and shipping paid for this purchase, in US dollars. |
| `--notes <text>` | Free-text notes about this purchase. |
| `--purchase-date <YYYY-MM-DD>` | Date of purchase; defaults to today. |
| `--form` | Prompt for a catalog coffee, quantity, total cost, and notes; the purchase date is set to today. |

Examples:

```bash
purvey inventory add --catalog-id 128 --qty 10 --cost 85.00 --pretty
purvey inventory add --manual-name "Farm-gate Ethiopia lot 7" --qty 12 --cost 96 --pretty
```

## purvey inventory update

Update an inventory item.

Usage: `purvey inventory update <id> [options]`

Access: Member. Requires member access on your account.

| Argument or flag | Details |
| --- | --- |
| `<id>` | Required: Inventory ID of the item. |
| `--qty <lbs>` | New purchased quantity, in pounds. |
| `--cost <dollars>` | New total bean cost, in US dollars (not the price per pound). |
| `--tax-ship <dollars>` | New tax and shipping amount, in US dollars. |
| `--notes <text>` | Replace the notes for this item. |
| `--stocked <true\|false>` | Mark the coffee as in stock (true) or used up (false). |
| `--rank <n>` | Your own whole-number ranking for this coffee, used to order your inventory. |

## purvey inventory delete

Delete an inventory item.

Usage: `purvey inventory delete <id> [options]`

Access: Member. Requires member access on your account.

| Argument or flag | Details |
| --- | --- |
| `<id>` | Required: Inventory ID of the item. |
| `--yes` | Delete without asking for confirmation; needed in scripts and agents. |

## Related

- [Roast commands](https://www.purveyors.io/docs/cli/roast): Inventory IDs feed roast create, import, and watch.
- [Beans page](https://www.purveyors.io/beans): Manage inventory in the web app.
- [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group.