Roast commands

purvey roast list

• --coffee-id expects inventory_id, not catalog_id.
• --catalog-id filters by catalog ID.
• --date-start and --date-end accept YYYY-MM-DD format.
• --search takes up to 100 characters and is matched as written: % and _ are ordinary characters, and * stands for any one character. A number finds the roast with exactly that ID, and any roast with the number in its coffee or batch name. Search text that is refused exits 2; the message calls the search text q.
• Every filter narrows the list together: --search with --coffee-name, --batch-name, or --roast-id returns only roasts that match all of them.
• --wholesale false includes roasts of coffees with no catalog listing, so true and false together cover every roast.
• --include-totals adds meta.totals { roasts, batches, average_loss_percent } for every roast the filters match, the same on every page. average_loss_percent is null when no matching roast has a recorded weight loss. An empty result prints data: [] with totals of zero. It does not support --csv.
• Paging: raise --offset by --limit. With --include-totals, a page is the last one when --offset plus the number of roasts returned reaches meta.totals.roasts.
• Without --include-totals the output is a list of roasts, and an empty result prints nothing on stdout.
• Every roast includes batch_id, the ID of the batch it belongs to.
• artisan_file_available is true when roast artisan-file can return the Artisan file the roast was imported from.

purvey roast list --search "guji" --include-totals
purvey roast list --wholesale false --limit 20 --offset 20
purvey roast list --date-start 2026-03-01 --date-end 2026-03-31
purvey roast list --batch-id 7c1d4e2a-9b3f-4a6c-8d5e-2f1a0b9c8d7e

purvey roast get

• artisan_file_available is true when roast artisan-file can return the Artisan file the roast was imported from.

purvey roast chart

• Returns the roast chart data unchanged: sampled series, events, and metadata.
• data.metadata.revision identifies the immutable chart revision used by reference-profile compare.

purvey roast chart 123 --pretty
purvey roast chart 123 --target-points 120 | jq '.data.metadata.revision'

purvey roast artisan-file

• Writes the file byte for byte, checks it against its SHA-256, and prints a JSON receipt: data.path, data.bytes, data.sha256. A file that fails the check is removed.
• Requires Studio access on your account; API keys need the roast:read scope.
• A roast has a file when artisan_file_available is true in roast get or roast list. Roasts entered by hand, logged live, or imported before files were kept have none; the error message says which.

purvey roast artisan-file 123
purvey roast artisan-file 123 --output ~/artisan/

purvey roast create

• Pass --batch-id or --batch-name, not both. The created roast includes batch_id.

purvey roast update

• --batch-id and --batch-name move this roast between batches. To rename a batch, use roast-batch update --name.

purvey roast delete

• Deleting the last roast in a batch leaves the batch in place, empty. Remove it with roast-batch delete.

purvey roast import

• Pass --batch-id or --batch-name, not both.
• The result includes batch_id; pass it as --batch-id to import the next file into the same batch.

purvey roast from-reference

• Creates the roast from the Artisan file uploaded with reference-profile import, so the .alog file does not need to be on this machine.
• Only an uploaded Artisan reference can become a roast. A generated plan is never recorded as a roast, and a reference saved from a past roast is refused because that roast is already in your history.
• Output is the created roast with its curve, an import summary, and the reference it came from.
• Pass --batch-id or --batch-name, not both.
• Requires a member credential and Studio access on your account.

purvey roast from-reference 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --coffee-id 7 --pretty

purvey roast watch

• --auto-match is mutually exclusive with --coffee-id.
• --auto-match matches each new roast to a stocked inventory item from its metadata.
• --commit-mode defaults to batch so new roasts are queued until the session ends.
• In batch commit mode the session opens one new batch, named by --batch-prefix, and saves every roast into it by batch ID. It stays one batch when the name was used before and when the session runs past midnight. The closing summary prints the batch ID.
• --resume keeps adding to the same batch. A session saved by an earlier CLI version, which stored only the batch name, continues in the batch that holds its first saved roast.
• The batch is opened when the first roast is saved. If no roast is saved into it, for example when every import fails, it is removed when the session ends.
• In individual commit mode each roast is its own batch, named "<name> #1", "<name> #2", and so on.

Related links