CookCLI

CookCLI is a command‑line driven engine for the Cooklang recipe markup language. It parses plain‑text .cook files, applies unit conversion and scaling logic, generates shopping lists, and can expose the same data through a lightweight HTTP server. The tool is written in Rust for performance, safety, and cross‑platform binaries, making it ideal for embedding into CI pipelines, home automation scripts, or personal kitchen dashboards.

Technical Stack

• Language: Rust 1.70+, leveraging the clap crate for argument parsing and serde for data serialization.
• Core Libraries: The project bundles a custom Cooklang parser (cooklang-core) that tokenizes ingredient quantities, timers, and recipe metadata. It uses chrono for time handling and regex for pattern matching.
• Data Persistence: By default CookCLI operates on the filesystem; recipes are stored as plain text files in a user‑specified directory. No external database is required, but the API can be extended to read from a SQLite or PostgreSQL backend via feature flags.
• Web Server: The built‑in server is powered by warp, a minimal async HTTP framework. It serves static HTML generated from the recipes and exposes a small JSON API (/api/v1/recipes) for programmatic access.

Core Capabilities

• Recipe Parsing & Validation: Detects syntax errors, missing metadata, and provides detailed diagnostics.
• Shopping List Generation: Aggregates ingredient quantities across multiple recipes, normalizes units, and sorts by pantry location.
• Scaling & Batch Processing: Adjusts ingredient amounts based on target servings, supporting fractional scaling (e.g., @flour{2%cups} → 4%cups for double servings).
• Reporting: Generates CSV/JSON reports on caloric content, ingredient sourcing, or nutritional breakdowns via optional plugins.
• Web API: Exposes endpoints for fetching recipe lists, individual recipes, and performing search queries. Supports CORS headers for integration with front‑end frameworks.

Deployment & Infrastructure

• Self‑Hosting: A single statically linked binary runs on any Unix‑like OS or Windows. No runtime dependencies are required beyond the standard library.
• Containerization: A Dockerfile is provided; the image uses scratch as a base, ensuring minimal attack surface. The server can be run in Kubernetes or Docker Compose with volume mounts for the recipe directory.
• Scalability: Because CookCLI is stateless and reads from disk, horizontal scaling can be achieved by running multiple instances behind a reverse proxy. For high‑concurrency workloads, the async server handles thousands of simultaneous API requests with negligible overhead.

Integration & Extensibility

• Plugin System: Developers can extend CookCLI via Rust cdylib plugins that implement the cookcli_plugin::Plugin trait. Plugins can hook into parsing, shopping list aggregation, or web API routes.
• Webhooks: The server accepts POST requests to /api/v1/webhook for real‑time updates (e.g., a smart fridge notifying of ingredient usage).
• CLI Hooks: Custom commands can be added by wrapping existing subcommands with shell scripts or Rust binaries, allowing integration into home automation (e.g., Home Assistant) or CI pipelines.

Developer Experience

• Configuration: A simple cookcli.toml file allows overriding defaults such as the recipe directory, unit preferences, or server port. Environment variables (COOKCLI_) provide an alternative for containerized deployments.
• Documentation: The README contains comprehensive usage examples, and the API surface is fully typed with RustDoc comments. Community resources include a dedicated Discord channel for plugin developers and an issue tracker for feature requests.
• Licensing: MIT license encourages commercial use without copyleft restrictions, making CookCLI suitable for proprietary kitchen management systems.

Use Cases

1. Smart Kitchen Dashboards – Embed CookCLI in a Raspberry Pi running a local web server, exposing recipes and shopping lists to a touch screen.
2. Automated Meal Planning – Use the CLI in GitHub Actions to generate weekly shopping lists from a repository of recipes, ensuring consistent pantry inventory.
3. Custom Recipe API – Deploy CookCLI behind an NGINX reverse proxy to provide a lightweight, self‑hosted API for mobile or web apps that need real‑time recipe data.

Advantages Over Alternatives

• Zero External Dependencies: No database or external services are required, simplifying deployment and reducing attack surface.
• High Performance: Rust’s zero‑cost abstractions mean parsing large recipe collections completes in milliseconds, even on low‑end hardware.
• Extensibility: The plugin interface and webhooks allow developers to add domain‑specific logic (e.g., ingredient cost calculation) without modifying core code.
• Open Source & Community‑Driven: A growing ecosystem of parsers and integrations across languages ensures future compatibility and shared best practices.

CookCLI offers a robust, developer‑friendly foundation for any project that needs reliable recipe parsing, shopping list generation, and a lightweight web interface—all packaged in a single, self‑contained binary.