Roasting

Reference profile commands

Import, compare, adjust, save, and export Studio reference roast plans, from an Artisan file or a past roast, and download the original Artisan file.

Work with your saved references and plans: compare roasts against a reference, preview and save plan changes, export a plan as an Artisan file for your next batch, and download the Artisan file a reference was added from.

Access: Member. Requires member access on your account.

View as Markdown

purvey reference-profile list

List your Studio reference profiles.

Usage: purvey reference-profile list [options]

Access: Member. Requires member access on your account.

Requires a member credential and Studio access on your account.
artisanFileAvailable is true when reference-profile artisan-file can return the original Artisan file.

Argument or flag	Details
`--include-archived`	Also list reference profiles you have archived.

Examples

purvey reference-profile list --pretty

purvey reference-profile get

Get one reference profile and its current revision.

Usage: purvey reference-profile get <profile-id>

Access: Member. Requires member access on your account.

Use data.currentRevision.id for chart, preview, and save.

Argument or flag	Details
`<profile-id>`	Required: Reference profile UUID.

Examples

purvey reference-profile get 5ea1af6f-234c-43a9-9bf8-5678dd24f854 --pretty

purvey reference-profile chart

Get the Artisan chart for a reference revision.

Usage: purvey reference-profile chart <profile-id> <revision-id>

Access: Member. Requires member access on your account.

Argument or flag	Details
`<profile-id>`	Required: Reference profile UUID.
`<revision-id>`	Required: Revision UUID belonging to the profile.

Examples

purvey reference-profile chart 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --pretty

purvey reference-profile import

Upload an Artisan file as a private Studio reference profile.

Usage: purvey reference-profile import <file> [options]

Access: Member. Requires member access on your account.

The uploaded file is parsed on purveyors.io and kept private to your account.
Reuse an explicit idempotency key to replay the same upload.
Import creates a reference profile, not executed roast history.

Argument or flag	Details
`<file>`	Required: Path to an Artisan .alog or importer-supported JSON file.
`--title <text>`	Title for the new reference profile.
`--notes <text>`	Notes about the reference profile.
`--idempotency-key <key>`	Key that makes retries safe: repeating the upload with the same key does not create a second profile. A new key is generated when omitted.

Examples

purvey reference-profile import ~/artisan/ethiopia.alog --title "Ethiopia baseline"

purvey reference-profile compare

Compare two immutable roast or reference revisions with measured deltas.

Usage: purvey reference-profile compare <left> <right> [options]

Access: Member. Requires member access on your account.

Output is the comparison result unchanged.
profile:<uuid> resolves the profile currentRevisionId; roast:<roast-id> resolves data.metadata.revision from roast chart data.
Both sides are aligned at charge; a reference profile is never executed roast history.

Argument or flag	Details
`<left>`	Required: selector: revision:<uuid>, profile:<uuid>, roast:<roast-id>, or roast:<roast-id>@<chart-revision>.
`<right>`	Required: selector: revision:<uuid>, profile:<uuid>, roast:<roast-id>, or roast:<roast-id>@<chart-revision>.
`--unit <F\|C>`	Temperature unit for the compared series: F (Fahrenheit) or C (Celsius). Default: F.
`--target-points <n>`	Number of samples in each aligned temperature series. Default: 400. Range: 50 to 1000.

Examples

purvey reference-profile compare roast:123 profile:5ea1af6f-234c-43a9-9bf8-5678dd24f854 --pretty
purvey reference-profile compare roast:123 roast:124 --unit C --json

purvey reference-profile roasts

List your past roasts that a plan can be built from.

Usage: purvey reference-profile roasts [options]

Access: Member. Requires member access on your account.

Lists roasts with an Artisan file on record; each entry has the roastId and roastRevision that preview-from-roast and from-roast accept, and the reference the roast is or would be saved under.
data.ineligibleRoastCount counts your other roasts: entered by hand, logged live, imported before Artisan files were kept, or holding a file too large for a reference. Those cannot be a plan base.
Requires a member credential and Studio access on your account.

Argument or flag	Details
`--limit <n>`	Number of roasts to list, newest first. Default: 15. Range: 1 to 50.

Examples

purvey reference-profile roasts --pretty

purvey reference-profile preview

Preview bounded temperature adjustments without saving.

Usage: purvey reference-profile preview <profile-id> <revision-id> [options]

Access: Member. Requires member access on your account.

Request JSON contains title, optional notes, optional userGoal (600 chars), modelRecommendation (800), and userEdits (800) provenance, and changes.temperatureAdjustments; each adjustment has kind, startMilliseconds, endMilliseconds, and delta.
At most 12 adjustments are accepted; intervals must be ordered and each nonzero delta is bounded to -20 through 20.
The plan is recalculated from the unchanged parent revision; preview never saves anything.

Argument or flag	Details
`<profile-id>`	Required: Reference profile UUID.
`<revision-id>`	Required: Revision UUID to adjust; it is never changed.
`--request <file>`	Required. JSON file with a title and up to 12 temperature adjustments; save accepts the same file.

Examples

purvey reference-profile preview 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --pretty

purvey reference-profile preview-from-roast

Preview a plan built from one of your past roasts without saving.

Usage: purvey reference-profile preview-from-roast <roast-id> [options]

Access: Member. Requires member access on your account.

Nothing is saved and the roast is not changed. The result is a plan, never a roast you ran.
data.parentProfileId and data.parentRevisionId name the reference this roast is saved under; data.parentSaved says whether from-roast --artisan-source has saved it yet.
A roast with no Artisan file on record exits 2 with a message that says why and what to do next.

Argument or flag	Details
`<roast-id>`	Required: ID of a past roast with an Artisan file on record.
`--request <file>`	Required. JSON file with a title and up to 12 temperature adjustments; preview and save accept the same file.
`--roast-revision <token>`	The roast's revision from reference-profile roasts, to plan from exactly the roast you looked at. The roast's current revision is used when omitted.

Examples

purvey reference-profile preview-from-roast 4529 --request changes.json --pretty

purvey reference-profile from-roast

Save one of your past roasts as a reference profile.

Usage: purvey reference-profile from-roast <roast-id> [options]

Access: Member. Requires member access on your account.

With --artisan-source, saving the same roast again returns the reference already saved from it. Pass data.id and data.currentRevisionId to save to store the plan.
The roast is never changed, and the reference is not a second roast.
A roast with no Artisan file on record exits 2 with a message that says why and what to do next.

Argument or flag	Details
`<roast-id>`	Required: ID of the past roast to save as a reference.
`--artisan-source`	Keep the roast's Artisan file with the reference so a plan can be built from it. Without this flag the reference is a chart for comparison only.
`--roast-revision <token>`	The roast's revision from reference-profile roasts, to save exactly the roast you looked at. The roast's current revision is used when omitted.
`--title <text>`	Title for the reference profile.
`--notes <text>`	Notes about the reference profile.
`--idempotency-key <key>`	Key that makes retries safe: repeating the command with the same key does not create a second reference. A new key is generated when omitted.

Examples

purvey reference-profile from-roast 4529 --artisan-source --pretty

purvey reference-profile save

Save changes as a new immutable generated reference plan.

Usage: purvey reference-profile save <profile-id> <revision-id> [options]

Access: Member. Requires member access on your account.

Reuse an explicit idempotency key to replay the same save.
To plan from a past roast, run from-roast --artisan-source first and pass the profile and revision ids it returns.
Generated references are plans and never create executed roast history.

Argument or flag	Details
`<profile-id>`	Required: Reference profile UUID.
`<revision-id>`	Required: Revision UUID the new plan is based on; it is never changed.
`--request <file>`	Required. The same JSON request file you previewed.
`--idempotency-key <key>`	Key that makes retries safe: repeating the save with the same key does not create a second plan. A new key is generated when omitted.

Examples

purvey reference-profile save 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --pretty

purvey reference-profile export

Download a saved generated reference as an unsigned Artisan .alog plan.

Usage: purvey reference-profile export <profile-id> <revision-id> [options]

Access: Member. Requires member access on your account.

Only a saved generated revision can be exported; output is a local file plus a JSON receipt.
The CLI does not claim verified Artisan 4.2 playback compatibility.

Argument or flag	Details
`<profile-id>`	Required: UUID of a saved generated reference profile.
`<revision-id>`	Required: UUID of the saved generated revision.
`--output <file>`	Required. Path to write the .alog file to.
`--force`	Overwrite the output file if it already exists.

Examples

purvey reference-profile export 0b7e9f52-3c61-4d8a-9e24-6f1a8c3d5b90 c43a1d7e-95b2-4e06-8f7c-1d2b3a4e5f68 --output ~/artisan/next-batch.alog

purvey reference-profile artisan-file

Download the Artisan file a reference was uploaded or saved from, exactly as stored.

Usage: purvey reference-profile artisan-file <profile-id> [options]

Access: Member. Requires member access on your account.

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 reference has an original file when artisanFileAvailable is true in reference-profile list. A planned profile has none; download it with reference-profile export.

Argument or flag	Details
`<profile-id>`	Required: Reference profile UUID.
`--output <path>`	File to write, or an existing folder to save the file in under its original name. Defaults to the current folder.
`--force`	Overwrite the output file if it already exists.

Examples

purvey reference-profile artisan-file 5ea1af6f-234c-43a9-9bf8-5678dd24f854 --output ~/artisan/

purvey reference-profile list

purvey reference-profile get

purvey reference-profile chart

purvey reference-profile import

purvey reference-profile compare

purvey reference-profile roasts

purvey reference-profile preview

purvey reference-profile preview-from-roast

purvey reference-profile from-roast

purvey reference-profile save

purvey reference-profile export

purvey reference-profile artisan-file

Related links