120 lines
3.8 KiB
Markdown
120 lines
3.8 KiB
Markdown
# Formulation CLI
|
|
|
|
The Formulation CLI is the supported local automation interface for recipes,
|
|
ingredients, purchases, prices, units, equipment, prep actions, inventory,
|
|
recipe books, archives, and database backups. It calls the same domain layer as
|
|
the web application instead of editing SQLite or generated files directly.
|
|
|
|
## Running it
|
|
|
|
From the repository:
|
|
|
|
```bash
|
|
npm run cli -- help
|
|
npm run cli -- recipe list --query chicken --limit 10
|
|
```
|
|
|
|
After `npm link`, the same commands can be invoked as `formulation ...`.
|
|
`formulation help recipe save` shows command-specific arguments. For agents and
|
|
other programs, `formulation cli commands --compact` returns the complete
|
|
command registry as JSON.
|
|
|
|
The default database is `var/recipe-book.sqlite`. Select another database with
|
|
`--database path/to/file.sqlite` or the `FORMULATION_DATABASE` environment
|
|
variable. An explicitly selected database takes precedence.
|
|
|
|
## Input and output
|
|
|
|
Simple fields can be options. Hyphens in option names map to underscores in
|
|
the domain payload and numbers, booleans, `null`, arrays, and objects are
|
|
coerced from JSON-compatible values.
|
|
|
|
```bash
|
|
formulation unit convert 2 kilogram gram
|
|
formulation recipe get RECIPE_ID --target-yield 4 --target-yield-unit kilogram
|
|
```
|
|
|
|
Nested writes should use a JSON object from a file or standard input:
|
|
|
|
```bash
|
|
formulation ingredient save --input ingredient.json
|
|
formulation recipe save RECIPE_ID --input recipe.json
|
|
Get-Content recipe.json | formulation recipe save --input -
|
|
```
|
|
|
|
Command-line values override fields supplied by `--input`. Successful commands
|
|
emit this stable envelope:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"command": "recipe get",
|
|
"dry_run": false,
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
Use `--compact` for one-line JSON. `--output file.json` writes the result to a
|
|
file and prints a small confirmation envelope. Database exports are written as
|
|
raw backup bundles so they can be passed directly to validate, diff, or import.
|
|
|
|
Errors are emitted to standard error:
|
|
|
|
```json
|
|
{"success":false,"error":{"code":"USAGE_ERROR","message":"..."}}
|
|
```
|
|
|
|
Exit codes are `0` for success, `2` for invalid commands or input, `3` for a
|
|
domain or validation rejection, and `4` for filesystem, database, or other
|
|
system failures.
|
|
|
|
## Safety
|
|
|
|
Add `--dry-run` to any mutation. The CLI copies the selected database, performs
|
|
the complete operation on the copy, returns the result, and deletes the copy.
|
|
The original database and generated site projection remain unchanged.
|
|
|
|
```bash
|
|
formulation recipe save RECIPE_ID --input recipe.json --dry-run
|
|
```
|
|
|
|
Include `expected_save_version` when updating a recipe. A stale version is
|
|
rejected, preventing an automation run from silently overwriting a newer edit.
|
|
|
|
Permanent archive deletion and database import require `--yes`. They can be
|
|
tested without confirmation using `--dry-run`.
|
|
|
|
## Command families
|
|
|
|
```text
|
|
recipe list, get, save, archive, quality, cost, nutrition
|
|
ingredient list, get, save, archive
|
|
purchase list, get, save, price
|
|
unit list, convert
|
|
equipment list
|
|
prep-action list
|
|
inventory list, get, create, update
|
|
book list, get, save
|
|
archive list, restore, purge
|
|
db stats, export, validate, import, diff
|
|
cli commands
|
|
```
|
|
|
|
IDs are positional where practical. Save commands accept the complete domain
|
|
object through `--input`; their required top-level fields are listed by
|
|
command-specific help.
|
|
|
|
## Backup workflow
|
|
|
|
```bash
|
|
formulation db export --output data/backup.json
|
|
formulation db validate --input data/backup.json
|
|
formulation db diff --input data/backup.json
|
|
formulation db import --input data/backup.json --dry-run
|
|
formulation db import --input data/backup.json --yes
|
|
```
|
|
|
|
Import defaults to transactional replacement. Pass `--mode merge` to merge the
|
|
bundle. A missing database selected with `--database` is created and migrated
|
|
before import. Invalid bundles are rejected before their contents are applied.
|