brewsorted-cli 0.8.4__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- brewsorted_cli/__init__.py +5 -0
- brewsorted_cli/_skill/SKILL.md +201 -0
- brewsorted_cli/_skill/__init__.py +1 -0
- brewsorted_cli/_skill/agents/openai.yaml +6 -0
- brewsorted_cli/_skill/references/cli.md +471 -0
- brewsorted_cli/_skill/tests/acceptance_scenarios.json +946 -0
- brewsorted_cli/_skill/tests/test_skill.py +534 -0
- brewsorted_cli/auth_state.py +273 -0
- brewsorted_cli/client.py +482 -0
- brewsorted_cli/http.py +29 -0
- brewsorted_cli/main.py +851 -0
- brewsorted_cli/oauth_discovery.py +120 -0
- brewsorted_cli/oauth_login.py +277 -0
- brewsorted_cli/product_feedback.py +114 -0
- brewsorted_cli/skills.py +45 -0
- brewsorted_cli/updates.py +76 -0
- brewsorted_cli-0.8.4.dist-info/METADATA +172 -0
- brewsorted_cli-0.8.4.dist-info/RECORD +21 -0
- brewsorted_cli-0.8.4.dist-info/WHEEL +5 -0
- brewsorted_cli-0.8.4.dist-info/entry_points.txt +2 -0
- brewsorted_cli-0.8.4.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,471 @@
|
|
|
1
|
+
# BrewSorted CLI reference
|
|
2
|
+
|
|
3
|
+
## Product feedback
|
|
4
|
+
|
|
5
|
+
`brewsorted product-feedback submit --input -` reads a JSON object containing
|
|
6
|
+
only `message` from stdin; `--input @path` reads a file. Keep text out of command
|
|
7
|
+
arguments. The limit is 10,000 Unicode characters and accepted text is preserved.
|
|
8
|
+
Only explicit User instruction authorizes submission. It sends one private
|
|
9
|
+
report and returns `report_id` and `status: received`, without a browser link,
|
|
10
|
+
tracking or guaranteed reply. It is distinct from `suggestion-feedback`.
|
|
11
|
+
No report lookup exists. `feedback_delivery_uncertain` means storage may have
|
|
12
|
+
succeeded; another submission requires new explicit intent accepting a possible
|
|
13
|
+
duplicate. `feedback_rate_limited` includes `retry_after` seconds; never schedule
|
|
14
|
+
a retry automatically. Follow the skill's Product feedback consent rules.
|
|
15
|
+
|
|
16
|
+
## Coffee commands and Connection setup
|
|
17
|
+
|
|
18
|
+
The CLI emits one JSON document. Configure its exact API origin and optional
|
|
19
|
+
browser origin outside the conversation, then establish a protected local OAuth
|
|
20
|
+
Connection:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
export BREWSORTED_API_URL=https://coffee.example
|
|
24
|
+
export BREWSORTED_WEB_URL=https://coffee.example
|
|
25
|
+
install -d -m 0700 "$HOME/.local/state/brewsorted"
|
|
26
|
+
export BREWSORTED_STATE_FILE="$HOME/.local/state/brewsorted/auth.json"
|
|
27
|
+
brewsorted login --device
|
|
28
|
+
brewsorted status
|
|
29
|
+
brewsorted context
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
If the agent VM requires an HTTP proxy, use its standard `HTTPS_PROXY`
|
|
33
|
+
environment variable (for example, `http://proxy.example:8080`) for the HTTPS
|
|
34
|
+
service. `HTTP_PROXY`, fallback `ALL_PROXY`, destination bypass `NO_PROXY`, and
|
|
35
|
+
lowercase equivalents are supported. A global
|
|
36
|
+
`brewsorted --proxy http://proxy.example:8080 login --device` overrides all
|
|
37
|
+
proxy and bypass environment settings. Keep the same environment or explicit
|
|
38
|
+
option for later commands; proxy configuration also covers signing keys,
|
|
39
|
+
refresh and logout and is not stored in the Connection. Keep proxy credentials
|
|
40
|
+
in the protected environment outside chat. TLS verification stays enabled;
|
|
41
|
+
use the VM's trusted CA bundle through `SSL_CERT_FILE`/`SSL_CERT_DIR` when needed.
|
|
42
|
+
|
|
43
|
+
Keep the device-login process alive and relay only its exact verification URL
|
|
44
|
+
and short code. The intended User authorizes in their own browser. Never ask for
|
|
45
|
+
SSH access, a password, tokens, or recovery links. `status` is anonymous service
|
|
46
|
+
health; `context` is the authenticated check and refreshes an expired access
|
|
47
|
+
token from the protected binding when needed. Disposable CRUD with exact
|
|
48
|
+
Qualified IDs is separate write/read-back evidence.
|
|
49
|
+
|
|
50
|
+
Never request, display, paste, or echo an access token in chat or a command argument.
|
|
51
|
+
The CLI stores its protected Connection outside chat, sends access tokens only as
|
|
52
|
+
Bearer credentials to the exact configured HTTPS origin, and does not follow
|
|
53
|
+
redirects. HTTP API origins are accepted only on loopback for development. The
|
|
54
|
+
web URL is independent and is the origin a person can open in a browser. When
|
|
55
|
+
configured, item and list results include a `web_url`; brew comparisons include
|
|
56
|
+
`left_web_url` and `right_web_url`. Return those exact links for records you
|
|
57
|
+
mention. When those fields are absent, do not construct a substitute.
|
|
58
|
+
|
|
59
|
+
Every User-owned record uses the complete Qualified ID returned by the API,
|
|
60
|
+
such as `alex/41`. Never pass a bare number or combine the current Username with
|
|
61
|
+
a remembered number. Collections and name searches are already relative to the
|
|
62
|
+
authenticated User.
|
|
63
|
+
|
|
64
|
+
## Operational boundary
|
|
65
|
+
|
|
66
|
+
For coffee-journal work, use only the documented CLI commands in this reference
|
|
67
|
+
and `brewsorted --help` or resource help. Source code, application schemas,
|
|
68
|
+
migrations, direct database access, undocumented HTTP requests, and application
|
|
69
|
+
changes are outside the operational capability surface. A separately authorized
|
|
70
|
+
repository-development task is not journal operation and may use its own tools.
|
|
71
|
+
|
|
72
|
+
If no documented CLI operation can produce the requested outcome, stop before
|
|
73
|
+
writing and report the requested outcome, current supported behavior, observed
|
|
74
|
+
limitation, user impact, desired capability, and known affected record IDs or
|
|
75
|
+
emitted links (`unknown` when none were identified). State the needed outcome
|
|
76
|
+
without prescribing its implementation. Do not substitute another
|
|
77
|
+
classification, fabricate a placeholder or duplicate, promise the missing
|
|
78
|
+
feature, or rewrite history. Any later reconciliation starts from identified
|
|
79
|
+
records and fresh user authorization.
|
|
80
|
+
|
|
81
|
+
First distinguish a capability gap from an incomplete lookup. `context` is
|
|
82
|
+
bounded. Search the relevant catalog and use its documented get operation when
|
|
83
|
+
needed. When the user genuinely requested a new Brew method, Drink type,
|
|
84
|
+
Equipment item, or other creatable catalog entity, check for duplicates and use
|
|
85
|
+
the supported create command.
|
|
86
|
+
|
|
87
|
+
## Health and lookup
|
|
88
|
+
|
|
89
|
+
`status` and `context` may include a version-only `client_update` advisory.
|
|
90
|
+
`brewsorted updates` checks the configured service anonymously and reports
|
|
91
|
+
`current_version`, `recommended_version`, and `update_available`; null means
|
|
92
|
+
unknown. It does not install anything. After completing a coffee request, use
|
|
93
|
+
`brewsorted updates --claim-reminder` for a known advisory and append a reminder
|
|
94
|
+
only if `reminder_due` is true. Claims share a rolling 24-hour cooldown across
|
|
95
|
+
sessions and release versions using the same configured state file. The
|
|
96
|
+
timestamp lives in a separate mode-0600 `.update-reminder` file beside it;
|
|
97
|
+
unavailable metadata or unsafe/unwritable state suppresses unsolicited advice.
|
|
98
|
+
An explicit update question uses the plain command without claiming a reminder.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
brewsorted status
|
|
102
|
+
brewsorted context
|
|
103
|
+
brewsorted roasteries list --q "Square Mile"
|
|
104
|
+
brewsorted coffees list --q "Red Brick"
|
|
105
|
+
brewsorted coffees get alex/3
|
|
106
|
+
brewsorted bags list --coffee-id alex/3 --active
|
|
107
|
+
brewsorted bags get alex/21
|
|
108
|
+
brewsorted equipment list --q "Comandante" --type grinder
|
|
109
|
+
brewsorted equipment get alex/7
|
|
110
|
+
brewsorted equipment list --q "V60" --type brewer
|
|
111
|
+
brewsorted equipment list --tag travel
|
|
112
|
+
brewsorted equipment-types list
|
|
113
|
+
brewsorted brew-methods list --q "Pour-over"
|
|
114
|
+
brewsorted brew-methods get alex/2
|
|
115
|
+
brewsorted drink-types list --q "Flat white"
|
|
116
|
+
brewsorted drink-types get alex/5
|
|
117
|
+
brewsorted water-profiles list --q "Third Wave Water"
|
|
118
|
+
brewsorted water-profiles get alex/6
|
|
119
|
+
brewsorted recipes list --q "Weekday V60"
|
|
120
|
+
brewsorted recipes get alex/7
|
|
121
|
+
brewsorted brews list --bag-id alex/21
|
|
122
|
+
brewsorted brews get alex/41
|
|
123
|
+
brewsorted brew-ratings list --brew-id alex/41
|
|
124
|
+
brewsorted brew-ratings get alex/12
|
|
125
|
+
brewsorted suggestion-strategies list
|
|
126
|
+
brewsorted suggestions list --brew-id alex/41
|
|
127
|
+
brewsorted suggestions get alex/9
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Use `brewsorted context` to bootload a new agent session with up to ten distinct
|
|
131
|
+
recently used Equipment items, five Brew methods, Drink types, and active
|
|
132
|
+
Recipes, and the ten latest enriched Brews. Use its canonical `equipment` array; `devices` and
|
|
133
|
+
`grinders` are deprecated read projections for older clients. It is one bounded
|
|
134
|
+
API read and returns empty arrays for collections with no eligible records. When web links are
|
|
135
|
+
configured, each nested item has its own `web_url`.
|
|
136
|
+
|
|
137
|
+
## Identity preflight
|
|
138
|
+
|
|
139
|
+
Reuse a fresh `context` result within the session. Do not run it before every
|
|
140
|
+
write, and use `status` only for health. Resolve every identity the pending
|
|
141
|
+
mutation references: Coffee, physical Bag, Equipment, Brew method, Drink type,
|
|
142
|
+
Water profile, Recipe, or target Brew/Tasting. Search/get outside bounded context
|
|
143
|
+
when necessary. Coffee and Bag are separate identities; after resolving Coffee,
|
|
144
|
+
use `bags list --coffee-id ID --active` and ask when multiple physical Bags are
|
|
145
|
+
plausible. Rating resources have no author identity.
|
|
146
|
+
|
|
147
|
+
Names are not IDs. One clear result from a broadened catalog search may resolve
|
|
148
|
+
a distorted spoken name, such as searching for the distinctive `C40` token when
|
|
149
|
+
speech transcription mangles `Comandante`. Ask when multiple plausible matches
|
|
150
|
+
remain. Also ask before writing an ambiguous number or unit or a suspicious
|
|
151
|
+
transcription outlier. Do not silently normalize it; once clarified, an unusual
|
|
152
|
+
valid value is allowed. Show a concise proposed-record preview when that helps
|
|
153
|
+
resolve identity or classification, but do not demand another confirmation for
|
|
154
|
+
an unambiguous action the user already authorized. Recipe apply retains its
|
|
155
|
+
required preview and confirmation.
|
|
156
|
+
|
|
157
|
+
## Mutation verification
|
|
158
|
+
|
|
159
|
+
Send the smallest supported mutation once. For every successful non-delete
|
|
160
|
+
mutation, take the returned `id`, run the resource's documented `get ID`, and
|
|
161
|
+
compare important supplied fields and relationships against the saved item.
|
|
162
|
+
This applies to catalog records, Brews, ratings, Bag adjustments, and images.
|
|
163
|
+
After `recipes apply`, run `brews get RETURNED_ID` and compare the confirmed
|
|
164
|
+
draft, overrides, and `source_recipe_id`; do not apply again.
|
|
165
|
+
|
|
166
|
+
If the write returned success but the exact-record read fails, say that the
|
|
167
|
+
write succeeded, give its ID or emitted `web_url`, and label verification as
|
|
168
|
+
failed. If read-back succeeds with a discrepancy, report the mismatch without
|
|
169
|
+
issuing a corrective write.
|
|
170
|
+
|
|
171
|
+
For a transport or protocol failure with an uncertain mutation outcome, use
|
|
172
|
+
documented list/search reads and the supplied relationships, values, and time to
|
|
173
|
+
look for the result. Zero or multiple plausible matches leave the outcome
|
|
174
|
+
uncertain; do not choose the latest item or retry. If exactly one candidate
|
|
175
|
+
matches, read that candidate by ID and compare it before reporting success. Use
|
|
176
|
+
the resource's documented retrieval command when `get` is unavailable.
|
|
177
|
+
|
|
178
|
+
## Semantic payloads
|
|
179
|
+
|
|
180
|
+
Classify each supplied value before constructing a command: a user-stated fact,
|
|
181
|
+
a transparent calculation, a hypothesis, or unresolved input. Prefer measured
|
|
182
|
+
facts. Disclose arithmetic when it matters, but do not write derived response
|
|
183
|
+
fields back as inputs. Expected flavor, brewing advice, and agent hypotheses are
|
|
184
|
+
not observed Brew or Tasting data.
|
|
185
|
+
|
|
186
|
+
Direct Brew create uses the Brew method's `ratio_basis`: input water by default,
|
|
187
|
+
or beverage yield for explicitly configured methods. Use measured dose and the
|
|
188
|
+
corresponding liquid quantity, without a redundant `--ratio`:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
brewsorted brews create --coffee-bag-id alex/21 --dose-g 15 --water-g 240
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
When the supplied target is a ratio, omit `--water-g`:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
brewsorted brews create --coffee-bag-id alex/21 --dose-g 15 --ratio 16
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
For a beverage-yield method, direct ratio input declares actual yield instead of
|
|
201
|
+
water. Yield is extracted coffee before milk or dilution. Both water and yield
|
|
202
|
+
may be recorded, but the method selects the ratio basis. Do not infer that basis
|
|
203
|
+
from method names or Drink type. Legacy `method_params.yield_g` does not count as
|
|
204
|
+
the required canonical measurement.
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
brewsorted brew-methods create --name "Espresso" --ratio-basis beverage_yield
|
|
208
|
+
brewsorted brews create --coffee-bag-id alex/21 --brew-method-id alex/9 \
|
|
209
|
+
--dose-g 18 --beverage-weight-g 36
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
If the required measurement was not recorded, obtain explicit permission before
|
|
213
|
+
using `--acknowledge-missing-ratio-measurement`. The returned ratio is null and
|
|
214
|
+
`warnings` explains the missing measurement. Never invent water or yield. An
|
|
215
|
+
unrelated edit preserves the acknowledgement; supplying the quantity clears it.
|
|
216
|
+
Clearing a measured quantity or changing to a basis with a missing measurement
|
|
217
|
+
requires renewed acknowledgement.
|
|
218
|
+
|
|
219
|
+
A Brew PATCH may omit both and preserves unspecified values:
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
brewsorted brews update alex/41 --notes "Fast drawdown"
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Recipe create may have zero or one liquid target. Preview/apply merge omissions,
|
|
226
|
+
explicit values, and nulls under the Recipe override contract. A preview draft
|
|
227
|
+
can contain stored `water_g` plus derived `ratio`, while a read can also contain
|
|
228
|
+
read-only fields; neither response is a valid write payload. Build each create,
|
|
229
|
+
PATCH, preview, or apply request from the fields that operation accepts.
|
|
230
|
+
|
|
231
|
+
Put actual execution observations such as flow in Brew `notes`. Put tasted
|
|
232
|
+
sensory observations in `brew-ratings`; notes and diagnostics require no overall
|
|
233
|
+
score. Keep expected flavors and hypotheses out of Tasting records, and do not
|
|
234
|
+
add an author field. Extraction dose, water/yield, and beverage weight exclude
|
|
235
|
+
milk and dilution. Leave bloom, agitation, filter, beverage weight, Water
|
|
236
|
+
profile, TDS, and extraction yield unset unless the user actually supplied them.
|
|
237
|
+
|
|
238
|
+
Never substitute another Coffee, physical Bag, Equipment item, Brew method, or
|
|
239
|
+
Drink type. An optional classification can remain unset when that is meaningful
|
|
240
|
+
and disclosed. Required identity must be resolved; if the documented CLI cannot
|
|
241
|
+
do so, use the capability-gap workflow. Equipment does not imply method or
|
|
242
|
+
finished drink. A genuinely new user-requested catalog entry may still be
|
|
243
|
+
created after a duplicate search.
|
|
244
|
+
|
|
245
|
+
Keep a marketed Coffee product name intact and send supported attributes
|
|
246
|
+
separately, for example:
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
brewsorted coffees create --roastery-id alex/1 --name "Worka Sakaro" \
|
|
250
|
+
--origin-country Ethiopia --producer-farm Worka \
|
|
251
|
+
--varietal Heirloom --process natural
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Use only supported Coffee fields and update existing catalog IDs in place. The
|
|
255
|
+
user-supplied/confirmed URL and image policy still applies.
|
|
256
|
+
|
|
257
|
+
## Create records
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
brewsorted images upload /path/to/logo.png
|
|
261
|
+
brewsorted roasteries create --name "Square Mile" --country UK \
|
|
262
|
+
--website "https://shop.squaremilecoffee.com" \
|
|
263
|
+
--image-id "d9428888-122b-41e1-b85c-61cd3cbb3210"
|
|
264
|
+
brewsorted coffees create --roastery-id alex/1 --name "Red Brick" --process washed \
|
|
265
|
+
--product-url "https://shop.squaremilecoffee.com/red-brick" \
|
|
266
|
+
--image-id "d9428888-122b-41e1-b85c-61cd3cbb3210"
|
|
267
|
+
brewsorted bags create --coffee-id alex/1 --roast-date 2026-08-28 --weight-g 250
|
|
268
|
+
brewsorted equipment create --name "Comandante C40" --type grinder \
|
|
269
|
+
--grinder-kind hand --burr-type conical --setting-scale stepped \
|
|
270
|
+
--scale-description "Clicks from zero" --scale-minimum 0 \
|
|
271
|
+
--scale-maximum 60 --scale-step 1 --scale-direction higher_is_coarser \
|
|
272
|
+
--tag filter --image-id UUID
|
|
273
|
+
brewsorted equipment create --name "Hario V60" --type brewer \
|
|
274
|
+
--brewer-kind pour-over --image-id UUID
|
|
275
|
+
brewsorted water-profiles update alex/1 --image-id UUID
|
|
276
|
+
brewsorted drink-types update alex/1 --image-id UUID
|
|
277
|
+
brewsorted brew-methods create --name "Cold drip" \
|
|
278
|
+
--description "Slow percolation through a coffee bed"
|
|
279
|
+
brewsorted brew-methods update alex/1 --image-id UUID
|
|
280
|
+
brewsorted brews create --coffee-bag-id alex/1 --brewer-id alex/2 --grinder-id alex/1 \
|
|
281
|
+
--brew-method-id alex/1 --grind-setting 22 --dose-g 15 --ratio 16 \
|
|
282
|
+
--water-temp-c 94 --total-time-s 2:30
|
|
283
|
+
brewsorted recipes create --name "Weekday V60" --brewer-id alex/2 \
|
|
284
|
+
--grinder-id alex/1 --grind-setting 22 --dose-g 15 --ratio 16 \
|
|
285
|
+
--instructions "Bloom, then pour in two stages"
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Use either typed flags or `--input -` for stdin JSON or `--input @path` for a
|
|
289
|
+
JSON file. Do not combine them.
|
|
290
|
+
|
|
291
|
+
Roastery `--website` and Coffee `--product-url` accept absolute HTTP(S) URLs
|
|
292
|
+
without credentials. Pass through only values the user supplied or confirmed.
|
|
293
|
+
Managed images accept JPEG, PNG, or WebP files. Upload first, then pass the
|
|
294
|
+
returned UUID through `--image-id` for a Roastery, Coffee, Equipment item,
|
|
295
|
+
Water profile, Drink type, or Brew method; clear an attachment with JSON null
|
|
296
|
+
in an update. Brew methods support create, list, get, update, and delete; create
|
|
297
|
+
requires a unique nonblank name, while description and image are optional.
|
|
298
|
+
Resolve a requested method with `brew-methods list --q` and use its ID. Equipment
|
|
299
|
+
never selects a method, and a custom method does not imply Suggestion support.
|
|
300
|
+
`images get USERNAME/UUID`
|
|
301
|
+
inspects metadata and `images delete USERNAME/UUID` soft-deletes an image only when none
|
|
302
|
+
of those catalog records references it.
|
|
303
|
+
|
|
304
|
+
Equipment types are fixed: `brewer`, `grinder`, `kettle`, `scale`, `server`,
|
|
305
|
+
`filter`, and `other`. Names are not unique. When a lookup has multiple plausible
|
|
306
|
+
matches, present each candidate's ID, type, and tags and ask the person to choose.
|
|
307
|
+
Primary Brew flags require the matching type. Repeat
|
|
308
|
+
`--additional-equipment-id` to preserve extra ordering, but never repeat an ID or
|
|
309
|
+
select one ID in both a primary slot and extras.
|
|
310
|
+
|
|
311
|
+
`--grind-setting` is a JSON number and requires `--grinder-id`. Read the chosen
|
|
312
|
+
Equipment first and apply only its recorded scale bounds and increment. Step alignment starts
|
|
313
|
+
at the scale minimum when present and at zero otherwise. Missing
|
|
314
|
+
scale values remain unknown: do not invent units, bounds, a step, direction, or
|
|
315
|
+
cross-grinder conversion. Brew reads may contain exact
|
|
316
|
+
`legacy_grind_setting`; if `grind_setting` is null, describe that legacy text as
|
|
317
|
+
unresolved rather than interpreting it.
|
|
318
|
+
|
|
319
|
+
## Read, update, and delete
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
brewsorted coffees get alex/1
|
|
323
|
+
brewsorted coffees update alex/1 --notes "Best after day 10"
|
|
324
|
+
brewsorted coffees delete alex/1
|
|
325
|
+
brewsorted brews history --coffee-id alex/1
|
|
326
|
+
brewsorted brews latest --coffee-id alex/1
|
|
327
|
+
brewsorted brews compare alex/10 alex/11
|
|
328
|
+
brewsorted recipes get alex/7
|
|
329
|
+
brewsorted recipes update alex/7 --water-temp-c 92
|
|
330
|
+
brewsorted recipes delete alex/7
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
## Preview and apply Recipes
|
|
334
|
+
|
|
335
|
+
```bash
|
|
336
|
+
brewsorted recipes preview alex/7 --coffee-bag-id alex/4
|
|
337
|
+
brewsorted recipes preview alex/7 --coffee-bag-id alex/4 --grind-setting 22
|
|
338
|
+
brewsorted recipes apply alex/7 --coffee-bag-id alex/4 --grind-setting 22
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
Preview first with the intended overrides. It performs no write and returns the
|
|
342
|
+
resolved `draft`, every ordered `issue`, and `can_create`. Do not invent values
|
|
343
|
+
for missing fields or inactive references. Present the draft and issues, then
|
|
344
|
+
apply only after `can_create` is true and the person confirms it. Use the same
|
|
345
|
+
overrides for apply. Recipe names are not unique, so resolve ambiguous list
|
|
346
|
+
matches by ID. Applying creates one ordinary Brew with copied instructions and
|
|
347
|
+
source identity; the Recipe itself is never evidence that brewing occurred.
|
|
348
|
+
|
|
349
|
+
Recipe defaults populate the Brew's quantities without duplicate input. Beverage
|
|
350
|
+
yield Recipes can use `--target-beverage-weight-g` or a ratio; that target is
|
|
351
|
+
distinct from actual `--beverage-weight-g` in preview/application overrides.
|
|
352
|
+
For explicit scaling use `--scale-from dose` or `--scale-from liquid`, supplying
|
|
353
|
+
only the anchor quantity, not the side being calculated. Editing quantities
|
|
354
|
+
without scaling preserves the other value. The target ratio stays fixed.
|
|
355
|
+
|
|
356
|
+
```bash
|
|
357
|
+
brewsorted recipes preview alex/7 --coffee-bag-id alex/4 --dose-g 20 --scale-from dose
|
|
358
|
+
brewsorted recipes preview alex/7 --coffee-bag-id alex/4 --beverage-weight-g 40 \
|
|
359
|
+
--allow-ratio-override
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Actual ratio deviations within 5% inclusive need no flag; larger deviations
|
|
363
|
+
require the User's explicit permission for `--allow-ratio-override`. This records
|
|
364
|
+
actual values, never edits the Recipe. For a deliberately unrecorded quantity,
|
|
365
|
+
clear its inherited default through `--input` with explicit null and add the
|
|
366
|
+
missing-measurement acknowledgement. Ratio-free Recipes remain usable. A stale
|
|
367
|
+
Recipe target basis must be explicitly replaced or cleared, not bypassed with
|
|
368
|
+
the deviation flag. Show preview warnings as well as blocking issues, then apply
|
|
369
|
+
the same confirmed overrides once.
|
|
370
|
+
|
|
371
|
+
## Ratings
|
|
372
|
+
|
|
373
|
+
```bash
|
|
374
|
+
brewsorted brew-ratings create --brew-id alex/11 --notes "Sweeter after cooling"
|
|
375
|
+
brewsorted brew-ratings update alex/12 --overall 8
|
|
376
|
+
brewsorted brew-ratings list --brew-id alex/11
|
|
377
|
+
brewsorted coffee-ratings create --coffee-id alex/1 --overall 5 --would-rebuy
|
|
378
|
+
brewsorted coffee-ratings list --coffee-id alex/1
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
A brew tasting needs at least one observation: an overall score, diagnostic
|
|
382
|
+
field, or nonblank notes. Overall is optional and must never be inferred. Use
|
|
383
|
+
JSON input with `"overall": null` to clear a score while retaining another
|
|
384
|
+
observation. Coffee-product ratings still require `--overall`.
|
|
385
|
+
|
|
386
|
+
## Grounded Suggestions, Attempts, and Feedback
|
|
387
|
+
|
|
388
|
+
```bash
|
|
389
|
+
brewsorted suggestion-strategies list
|
|
390
|
+
brewsorted suggestions create --brew-id alex/41
|
|
391
|
+
brewsorted suggestions create --brew-id alex/41 \
|
|
392
|
+
--strategy-id rules.filter-dial-in.v1
|
|
393
|
+
brewsorted suggestions list --brew-id alex/41 --outcome proposed \
|
|
394
|
+
--strategy-id rules.filter-dial-in.v1
|
|
395
|
+
brewsorted suggestions get alex/9
|
|
396
|
+
brewsorted suggestion-attempts create --suggestion-id alex/9 --brew-id alex/44
|
|
397
|
+
brewsorted suggestion-attempts get alex/3
|
|
398
|
+
brewsorted suggestion-feedback create --attempt-id alex/3 --outcome unclear \
|
|
399
|
+
--notes "Needs another cup"
|
|
400
|
+
brewsorted suggestion-feedback list --attempt-id alex/3
|
|
401
|
+
brewsorted suggestion-feedback get alex/7
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
Suggestion create accepts the optional body through `--input -` or
|
|
405
|
+
`--input @path` while retaining the required target `--brew-id`. Attempt create
|
|
406
|
+
retains `--suggestion-id`; its body may supply `brew_id` through a typed flag or
|
|
407
|
+
JSON input. Feedback create retains `--attempt-id`; its body may supply
|
|
408
|
+
`outcome` and optional nonblank `notes` through typed flags or JSON input.
|
|
409
|
+
|
|
410
|
+
The default strategy is deterministic and local. Repeat the API's frozen facts,
|
|
411
|
+
analysis runs, inference, proposed change, uncertainty, Knowledge card/source
|
|
412
|
+
snapshots, and insufficiency exactly enough to keep those categories distinct.
|
|
413
|
+
An insufficient result contains no fallback change. A missing score is not zero
|
|
414
|
+
and is never a reason to invent a diagnosis.
|
|
415
|
+
|
|
416
|
+
Before Attempt creation, read the later Brew and obtain explicit confirmation
|
|
417
|
+
that its different recorded grind setting tried the proposed direction. The API
|
|
418
|
+
captures numeric or exact legacy setting and Grinder scale context; neither the
|
|
419
|
+
CLI nor agent calculates a next setting. Before Feedback creation, obtain an
|
|
420
|
+
explicit `yes`, `no`, or `unclear`; append corrections as new Feedback rather
|
|
421
|
+
than interpreting a Tasting or score.
|
|
422
|
+
|
|
423
|
+
Configured Suggestion create/get/list output includes `web_url` with the stable
|
|
424
|
+
`/suggestions/{id}` route. Attempt and Feedback output includes
|
|
425
|
+
`suggestion_web_url` for that parent chain. Return only those emitted links.
|
|
426
|
+
|
|
427
|
+
## Bag inventory adjustments
|
|
428
|
+
|
|
429
|
+
```bash
|
|
430
|
+
brewsorted bag-adjustments create --bag-id alex/1 --change-g -18 \
|
|
431
|
+
--reason untracked_use --notes "Made coffee without logging a Brew"
|
|
432
|
+
brewsorted bag-adjustments create --bag-id alex/1 --remaining-weight-g 72 \
|
|
433
|
+
--reason correction --notes "Scale reading"
|
|
434
|
+
brewsorted bag-adjustments create --bag-id alex/1 --finish \
|
|
435
|
+
--reason finished_early --notes "Discarded the remainder"
|
|
436
|
+
brewsorted bag-adjustments list --bag-id alex/1
|
|
437
|
+
brewsorted bag-adjustments get alex/3
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
Use exactly one create mode. `--change-g` is signed: negative removes beans and
|
|
441
|
+
positive adds them. Prefer `--remaining-weight-g` when the user states what is
|
|
442
|
+
actually left. `--finish` reconciles to zero and dates the Bag; use it only for
|
|
443
|
+
an explicit finish request. Reasons are `correction`, `untracked_use`,
|
|
444
|
+
`spillage`, `finished_early`, or `other`. Adjustments are immutable and never a
|
|
445
|
+
substitute for changing an actually incorrect Brew dose.
|
|
446
|
+
|
|
447
|
+
## Exit codes
|
|
448
|
+
|
|
449
|
+
- `0`: success
|
|
450
|
+
- `2`: usage or local input error
|
|
451
|
+
- `3`: backend connection error
|
|
452
|
+
- `4`: API client error
|
|
453
|
+
- `5`: API server error
|
|
454
|
+
|
|
455
|
+
On failure, parse the problem document from stderr. A connection failure means
|
|
456
|
+
the local service may need `brewsorted-api serve --db ./coffee.db --port 8765`.
|
|
457
|
+
For `401`, report that authentication failed without asking for the token. For
|
|
458
|
+
`403`, report that the configured credential or User state cannot perform the
|
|
459
|
+
operation. Treat `404` as absent or inaccessible without probing foreign
|
|
460
|
+
existence. Treat `422 invalid_reference` as an invalid reference, re-resolve it
|
|
461
|
+
from authenticated collections, and never echo foreign-record detail.
|
|
462
|
+
|
|
463
|
+
## Finished drinks
|
|
464
|
+
|
|
465
|
+
Look up explicit drink names with `brewsorted drink-types list --q "Latte"`.
|
|
466
|
+
Create a custom type with `brewsorted drink-types create --name "Iced latte"`;
|
|
467
|
+
the catalog also supports get, update, and delete using standard resource forms.
|
|
468
|
+
Pass the returned ID as `--drink-type-id` to Brew create/update/list/history.
|
|
469
|
+
Clear an assignment with update JSON (`{"drink_type_id": null}`) through `--input`.
|
|
470
|
+
Drink type identifies what was served; Brew measurements describe extraction and
|
|
471
|
+
Tastings describe that finished drink. Unspecified types remain unclassified.
|