# Roast batch commands > List, open, rename, and delete roast batches by batch ID. HTML version: https://www.purveyors.io/docs/cli/roast-batch A batch is one roasting session and the roasts in it. Batch names can repeat, so these commands find a batch by its ID. Access: Member. Requires member access on your account. ## purvey roast-batch list List your roast batches, newest batch date first. Usage: `purvey roast-batch list [options]` Access: Member. Requires member access on your account. - A batch is one roasting session. Each batch has id, name, batch_date, roast_count, roast_ids, and coffee_ids (the inventory items roasted). - The date filters use the batch date, not the roast dates inside the batch. - A batch with no roasts is listed only with --include-empty, under a placeholder name. | Argument or flag | Details | | --- | --- | | `--name ` | Only batches with exactly this name; several batches can carry the same name. | | `--date-start ` | Only batches dated on or after this date. | | `--date-end ` | Only batches dated on or before this date. | | `--include-empty` | Also list batches that hold no roasts. | | `--limit ` | Maximum number of batches to return. Default: 20. Range: 1 to 200. | | `--offset ` | Number of batches to skip when paging. Default: 0. | Examples: ```bash purvey roast-batch list --pretty purvey roast-batch list --name "wednesday" --pretty ``` ## purvey roast-batch get Get one roast batch with the IDs of its roasts. Usage: `purvey roast-batch get ` Access: Member. Requires member access on your account. - List the full roasts with roast list --batch-id. | Argument or flag | Details | | --- | --- | | `` | Required: Batch ID. | ## purvey roast-batch create Open a new, empty roast batch to add roasts to. Usage: `purvey roast-batch create [options]` Access: Member. Requires member access on your account. - Always opens a new batch, even when another batch has the same name. - Add roasts with --batch-id on roast import, roast create, or roast from-reference. Roasts keep their own dates, so one batch can span days. - Until it holds a roast, the batch is listed only with --include-empty and reads with a placeholder name. - roast watch opens its own batch; use this when importing files one at a time. | Argument or flag | Details | | --- | --- | | `--name ` | Required. Name for the batch; other batches may already use it. | | `--date ` | Session date for the batch; defaults to today. | | `--idempotency-key ` | Key that makes retries safe: repeating the command with the same key does not open a second batch. A new key is generated when omitted. | Examples: ```bash purvey roast-batch create --name "wednesday" --pretty ``` ## purvey roast-batch update Rename or re-date a roast batch. Usage: `purvey roast-batch update [options]` Access: Member. Requires member access on your account. - Pass at least one flag. Other batches with the same name are not changed. | Argument or flag | Details | | --- | --- | | `` | Required: Batch ID. | | `--name ` | New name for this batch; it also appears on the batch's roasts and on sales recorded against it. | | `--date ` | New batch date; roast dates are not changed. | Examples: ```bash purvey roast-batch update 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e --name "wednesday decaf" ``` ## purvey roast-batch delete Delete one roast batch and the roasts in it. Usage: `purvey roast-batch delete [options]` Access: Member. Requires member access on your account. - Deletes this batch and every roast in it, with their temperature and event data. No other batch is touched, even one with the same name. - Sales recorded against the batch are kept: they keep the batch name and lose the link to the batch. - Output is the deleted batch ID, its name, and the IDs of the roasts deleted with it. | Argument or flag | Details | | --- | --- | | `` | Required: Batch ID. | | `--yes` | Delete without asking for confirmation; needed in scripts and agents. | Examples: ```bash purvey roast-batch delete 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e --yes ``` ## Related - [Roast commands](https://www.purveyors.io/docs/cli/roast): Add roasts to a batch and list the roasts in one. - [Sales commands](https://www.purveyors.io/docs/cli/sales): Record sales against a batch ID. - [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group.