grocy-cli

A command-line interface for managing a Grocy ERP instance. Supports products, stock tracking, locations, barcodes (with OpenFoodFacts integration), quantity units, and shopping locations.

Installation

go install grocy-cli@latest

Or build from source:

git clone <repo-url>
cd grocy-cli
go build -o grocy-cli .

Configuration

grocy-cli reads two environment variables:

Variable	Description	Example
GROCY_URL	Base URL of the Grocy REST API	http://192.168.1.107:9283/api
GROCY_API_KEY	API key for authentication	lrUiKojD...

You can also place a .env file in the working directory:

GROCY_URL="http://192.168.1.107:9283/api"
GROCY_API_KEY="your-api-key-here"

API keys can be managed at http://<your-grocy-host>/manageapikeys.

Usage

All commands support --json for machine-readable JSON output and --help for detailed usage.

Locations

Manage storage locations (Fridge, Freezer, Pantry, etc.).

grocy-cli locations list
grocy-cli locations create --name "Pantry" --description "Dry goods"
grocy-cli locations create --name "Freezer" --freezer
grocy-cli locations get 2
grocy-cli locations delete 5

Products

Manage product definitions. Products must exist before stock can be tracked.

grocy-cli products list
grocy-cli products create --name "Basmati Rice" --location-id 6
grocy-cli products create --name "Milk" --location-id 2 --shopping-location-id 2
grocy-cli products get 1
grocy-cli products edit 1 --name "Semi-Skimmed Milk"
grocy-cli products delete 5

Stock

Track stock levels by recording purchases, consumption, and transfers.

# View current stock
grocy-cli stock list

# Add stock (purchase)
grocy-cli stock add 5 --amount 2 --best-before 2026-03-06 --price 1.50
grocy-cli stock add 12 --best-before 2026-04-01 --shopping-location-id 2

# Consume stock
grocy-cli stock consume 5 --amount 1
grocy-cli stock consume 5 --amount 1 --spoiled

# Transfer between locations
grocy-cli stock transfer 5 --amount 1 --from 2 --to 3

# View expiring/missing items
grocy-cli stock volatile

Barcodes

Manage product barcodes and look up products via OpenFoodFacts.

# List all barcodes
grocy-cli barcodes list
grocy-cli barcodes list --product-id 3

# Look up a barcode on OpenFoodFacts
grocy-cli barcodes lookup 5000112637922

# Look up and auto-create the product in Grocy
grocy-cli barcodes lookup 5000112637922 --add

# Manually add a barcode to a product
grocy-cli barcodes add --product-id 5 --barcode "5000112637922"
grocy-cli barcodes add --product-id 5 --barcode "5000112637922" --last-price 2.50

# Delete a barcode entry
grocy-cli barcodes delete 3

Quantity Units

Manage units used for stock tracking (Piece, Pack, Bottle, etc.).

grocy-cli quantity-units list    # or: grocy-cli qu list
grocy-cli quantity-units create --name "Bottle" --name-plural "Bottles"

Shopping Locations

Manage stores where products are purchased.

grocy-cli shopping-locations list    # or: grocy-cli shops list
grocy-cli shopping-locations create --name "Tesco"

JSON Output

Add --json to any command for JSON output, useful for scripting:

grocy-cli --json products list | jq '.[].name'
grocy-cli --json stock list | jq '.[] | select(.stock_amount > 0)'

Project Structure

grocy-cli/
├── main.go              # Entry point
├── cmd/
│   ├── root.go          # Root command, config loading
│   ├── helpers.go       # Shared utilities (arg parsing, JSON output)
│   ├── locations.go     # locations subcommands
│   ├── products.go      # products subcommands
│   ├── stock.go         # stock subcommands
│   ├── barcodes.go      # barcodes subcommands
│   ├── quantity_units.go # quantity-units subcommands
│   └── shopping.go      # shopping-locations subcommands
└── client/
    ├── client.go        # HTTP client (auth, error handling)
    ├── types.go         # API type definitions
    ├── objects.go       # Generic CRUD via /objects/{entity}
    ├── stock.go         # Stock-specific endpoints
    └── barcodes.go      # Barcode lookup endpoints

Grocy API

This tool targets Grocy v4.5.0+. The OpenAPI spec is available at http://<your-grocy-host>/api.