Grocy Toolkit

A containerized CLI tool for managing Grocy kitchen and pantry entities. This tool helps you set up and maintain standardized configurations for your Grocy instance, including quantity units, locations, product groups, and custom entities for kitchen management.

Features

• Create standardized Grocy entities from JSON configuration files
• Clean up entities created by this tool
• Customizable with environment variables and command line options
• Fine-grained filtering to exclude specific entities by name
• Docker ready for easy deployment and integration
• Idempotent operations - create commands can be run multiple times safely

Documentation

We provide comprehensive documentation to help you get the most out of grocy-toolkit:

• Quick Start Guide - Get up and running in under 10 minutes
• Comprehensive Documentation - Complete reference
• Example Use Cases - Real-world workflows and examples
• Entity Field Reference - Detailed guide to field types
• Integration Examples - Integrate with other systems
• Contributing Guide - How to contribute to the project

Prerequisites

• A running Grocy instance with API access
• Docker (recommended) or Deno runtime

Quick Start

Using Docker

1. Clone this repository
2. Create a .env file based on the .env.example file
3. Run the tool using Docker Compose:

# Show help
docker compose run --rm grocy-toolkit

# Create all entities
docker compose run --rm grocy-toolkit create

# Clean up all entities
docker compose run --rm grocy-toolkit cleanup

# Create only units and locations
docker compose run --rm grocy-toolkit create --skip-groups --skip-entities

# Run in dry-run mode (no changes made)
docker compose run --rm grocy-toolkit create --dry-run

Using Deno

1. Clone this repository
2. Install Deno
3. Set up environment variables
4. Run the tool:

# Show help
deno task start

# Create all entities
deno task create

# Clean up all entities
deno task cleanup

Configuration

Environment Variables

Set these in a .env file or as environment variables:

Variable	Description	Default
GROCY_API_URL	URL to your Grocy API	(Required)
GROCY_API_KEY	Your Grocy API key	(Required)
LOG_LEVEL	Log level (DEBUG, INFO, WARN, ERROR)	INFO
UOM_CODES_PATH	Path to UOM codes JSON file	./data/uom-codes.json
LOCATIONS_PATH	Path to locations JSON file	./data/locations.json
PRODUCT_GROUPS_PATH	Path to product groups JSON file	./data/product-groups.json
KITCHEN_ENTITIES_PATH	Path to kitchen entities JSON file	./data/kitchen-entities.json
PANTRY_ENTITIES_PATH	Path to pantry entities JSON file	./data/pantry-preservation-entities.json
OUTDOOR_ENTITIES_PATH	Path to outdoor entities JSON file	./data/outdoor-cooking-entities.json

Command Line Options

Available subcommands:

• create: Create entities in Grocy
• cleanup: Clean up entities created by this tool

Options for both subcommands:

Option	Description
--skip-units	Skip processing all unit of measure codes
--skip-locations	Skip processing all locations
--skip-groups	Skip processing all product groups
--skip-entities	Skip processing all custom entities
--skip-unit-item=<n>	Skip specific unit of measure by name (can be used multiple times)
--skip-location-item=<n>	Skip specific location by name (can be used multiple times)
--skip-group-item=<n>	Skip specific product group by name (can be used multiple times)
--skip-entity-item=<n>	Skip specific custom entity by name (can be used multiple times)
--dry-run	Show what would be done without making changes
-v, --verbose	Enable verbose logging
-h, --help	Show help information

Data Files

The tool uses these JSON files for configuration:

• uom-codes.json: Unit of measure codes with their names and categories
• locations.json: Storage locations for food and kitchen items
• product-groups.json: Product categorizations
• kitchen-entities.json: Custom entities for kitchen management
• pantry-preservation-entities.json: Custom entities for pantry and food preservation
• outdoor-cooking-entities.json: Custom entities for outdoor cooking management

Customizing the Data

You can modify the JSON files in the data/ directory to customize the entities created by this tool. The Docker setup mounts this directory as a volume, so changes take effect without rebuilding the container.

Check out the Entity Field Reference for detailed guidance on creating your own custom entities. We also provide a template generator script to help you get started.

Examples

Setting Up a New Grocy Instance

# Create all entities
docker compose run --rm grocy-toolkit create

Cleaning Up Test Data

# Clean up specific entity types (keeping others)
docker compose run --rm grocy-toolkit cleanup --skip-units --skip-locations

Excluding Specific Items

# Create all units except "Pound" and "Kilogram"
docker compose run --rm grocy-toolkit create --skip-unit-item=Pound --skip-unit-item=Kilogram

# Create everything except the "Pantry" location
docker compose run --rm grocy-toolkit create --skip-location-item=Pantry

# Clean up all groups except "Grocery" and "Produce"
docker compose run --rm grocy-toolkit cleanup --skip-group-item=Grocery --skip-group-item=Produce

Previewing Changes

# See what would be created without making changes
docker compose run --rm grocy-toolkit create --dry-run --verbose

Integration with CI/CD

See the Integration Examples documentation for detailed examples of how to integrate grocy-toolkit with CI/CD pipelines, Home Assistant, Docker Compose, and more.

Use Cases

grocy-toolkit can be used to implement various helpful workflows in your kitchen and household:

• Kitchen Equipment Management System - Track appliances, maintenance, and documentation
• Meal Prep Optimization System - Streamline your weekly meal preparation process
• Grill and BBQ Management System - Optimize your outdoor cooking setup
• Pantry and Preservation System - Track home preserved foods and storage
• Recipe Development System - Create a structured system for developing recipes

See the Example Use Cases documentation for detailed workflows and implementations.

Project Structure

grocy-toolkit/
├── Dockerfile
├── README.md
├── docker-compose.yml
├── .env.example
├── .gitignore
├── src/              # Source code
│   ├── index.ts      # Entry point
│   ├── actions/      # Create/cleanup functionality
│   ├── types/        # Type definitions
│   ├── config/       # Configuration management
│   ├── cli/          # CLI argument parsing
│   └── utils/        # Shared utilities
├── data/             # JSON configuration files
└── docs/             # Documentation
    ├── comprehensive-documentation.md
    ├── quick-start-guide.md
    ├── example-use-cases.md
    ├── entity-field-reference.md
    ├── integration-examples.md
    ├── diagrams/     # Visual diagrams
    └── scripts/      # Utility scripts

License

MIT

Contributing

Contributions are welcome! Please see the Contributing Guide for details on how to contribute effectively to this project.