NemlAI CLI Documentation

The NemlAI CLI gives you four ways to interact with the platform:

• Web Terminal — a browser-based terminal at /cli
• Local Terminal — install via pip, yay, or apt and run nemlai from your own machine
• HTTP API — REST endpoints for curl, scripts, and AI agents
• Python SDK — import nemlai in your Python scripts for programmatic access

Quick Start

1. Create an account

curl -X POST https://nemlai.milops.org/cli/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simon",
    "email": "[email protected]",
    "password": "your-password",
    "nemlig_email": "[email protected]",
    "nemlig_password": "nemlig-password"
  }'

2. Log in and get a token

curl -X POST https://nemlai.milops.org/cli/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

# Response:
STATUS: ok
TOKEN nemlai_abc123...def456
EXPIRES 2026-03-31T00:00:00Z

3. Use the token

# Save your token
export NEMLAI_TOKEN="nemlai_abc123...def456"

# Use it with any endpoint
curl https://nemlai.milops.org/cli/api/whoami \
  -H "Authorization: Bearer $NEMLAI_TOKEN"

Web Terminal

Open /cli in your browser. No installation needed. You get a full terminal with command history (up/down arrows), tab completion, and Ctrl+C to cancel.

The web terminal uses a WebSocket connection, so commands execute instantly with live feedback.

Local Terminal

Install the nemlai package and get the same terminal experience running on your own machine. All logic stays on the server — the local CLI is just a thin client that sends commands over HTTP.

Install

# PyPI (all platforms)
pip install nemlai

# Arch Linux (AUR)
yay -S nemlai

# Ubuntu / Debian
sudo add-apt-repository ppa:milops/nemlai
sudo apt install nemlai

Run

# Start the interactive terminal
nemlai

# Or run a single command
nemlai help
nemlai whoami
nemlai basket items

Features

• Same commands as the web terminal
• Tab completion and command history (persisted across sessions)
• Secure login — password input is hidden, token saved to ~/.config/nemlai/token
• Colour-coded output (green for success, red for errors)
• Works with NEMLAI_TOKEN environment variable for scripts
• Single-command mode for piping: nemlai basket items | grep milk

Configuration

# Point to a different server
nemlai --url http://localhost:8090

# Use a specific token
nemlai --token nemlai_abc123...

# Or use environment variables
export NEMLAI_TOKEN="nemlai_abc123..."
export NEMLAI_URL="http://localhost:8090"
nemlai

Config is stored in ~/.config/nemlai/:

HTTP API

All endpoints live under /cli/api/. Responses are plain text with a consistent format:

STATUS: ok
<response body>

or on error:

STATUS: error
ERROR <message>
HINT <suggestion>

Public endpoints (no auth required)

Authenticated endpoints

Include Authorization: Bearer <token> header.

Generic command endpoint

You can also send any command as text:

curl -X POST https://nemlai.milops.org/cli/api/command \
  -H "Authorization: Bearer $NEMLAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "basket generate --size medium --date 2026-03-15"}'

Python SDK

Install

pip install nemlai

Usage

from nemlai import NemlAI

# Log in (returns a client with token)
client = NemlAI.login("[email protected]", "password")

# Or use an existing token
client = NemlAI(token="nemlai_abc123...")

# Account
me = client.whoami()
print(me)  # {'user': 'Simon', 'email': '...', ...}

# Generate a basket
result = client.basket.generate(size="medium", date="2026-03-15")
print(result)

# List basket items
items = client.basket.items()

# Search and add a product
results = client.basket.search("oat milk")
client.basket.add(query="oat milk")

# Remove or adjust items
client.basket.remove(item=3)
client.basket.adjust(item=7, quantity=2)

# Send basket to Nemlig
url = client.basket.send()
print(url)  # https://nemlig.com/basket?skus=...

# Orders
client.orders.refresh(password="nemlig-password")

# Settings and preferences
client.settings.show()
client.preferences.show()

# Household
client.household.info()

Custom base URL

# For local development
client = NemlAI(token="nemlai_...", base_url="http://localhost:8090")

All Commands

Account

Basket (Generer kurv)

Orders

Settings & Preferences

Analytics

Ask questions about your own spending. Filters accept either repeated flags or a comma-separated string, so multi-product or multi-category reports take one call instead of N.

Multi-value examples — both forms are equivalent and combine in one round-trip:

# Repeated flags (kubectl / gh / git convention; shell-safe for any name)
nemlai analytics spend --last 12m \
    --product vandmelon --product jordbær --product hindbær --product gifler

# Comma-separated (ergonomic shortcut)
nemlai analytics spend --last 12m --product "vandmelon,jordbær,hindbær,gifler"

# Categories work the same way
nemlai analytics spend --last 3m --category "Grønt,Frost"
nemlai analytics trend --category Mejeri --category Drikke --bucket month --last 12m

• analytics spend --product "jordbær,hindbær" --exclude "Yoghurt,Hindbærtærte" --last 12m — exclude fuzzy-matched substring noise
• analytics spend --exclude-category "Kød & fisk" --last 30d — standalone category exclusion
• analytics spend --product hindbær --exclude-sku 5070590 --last 12m — exact product-number exclusion, no fuzzy matching
• analytics spend --last since-first-order --shop nemlig — full history, one shop only (--shop accepts nemlig, bilka, foetex; repeat for several)
• analytics spend --last ytd --hide-excluded — leave out orders/lines you excluded in the web dashboard
• analytics trend --last 7d --bucket auto — let the CLI pick the bucket size
• analytics top products --last 12m --compare previous-period — compare with the equally long period before
• analytics overview --from 2026-01-01 --to 2026-06-30 --bucket month — the Overblik tab for a custom range
• analytics top categories --level category_level --category-main Mejeri --last 12m — rank one level of the hierarchy within a filter
• analytics drill --order id:42 — one order by its internal id

Date range grammar — --last 7d, --last 30d, --last 3m, --last 12m, --last 2y, this-month, last-month, ytd, this-year, last-year, since-first-order (your whole history; exempt from the 5-year cap, no --compare), or --from 2026-01-01 --to 2026-03-31. With no range, commands default to the last 30 days; the maximum range is 5 years. All terms must be in Danish (Nemlig stores names in Danish: mælk not milk).

Comparisons & savings — --compare previous-period (or a bare --compare) on spend and top adds the equally long period before, with the change in kr and %; JSON has comparison.previous_total, delta_absolute and delta_pct. Campaign discounts are always reported as a positive saved amount (total_discount, per-line discount_amount). Periods are shown as local Copenhagen dates (date_range.start/end).

Scope & format — --scope household (default) covers every order in your household, --scope me only your own. --format table|json|csv|markdown controls the output: the SDK draws the table itself from the server's JSON (canonical variants, comparison change, saved amount, truncation and bucket notes); json, csv and markdown come straight from the server. Errors return HTTP 4xx/5xx with a STATUS: error / ERROR / HINT body. Category names can also be filtered through the catalog hierarchy with --category-main, --category-level and --category-sub (plus --exclude-category-main/-level/-sub). The same data is available in the web dashboard at /analytics.

Python — every command is a typed method: NemlAI(token=...).analytics.overview(last="3m"), .spend(product=["mælk"], category="Mejeri", compare="previous-period"), .top("categories", level="sub"), .trend("month"), .drill(order="0042"), .receipts(...), .categories_tree(). Errors raise nemlai.AnalyticsError with message, hint and status_code.

Other

Authentication

The CLI uses token-based authentication. Tokens are long-lived (30 days by default) and can be revoked with logout.

For the Web Terminal

Just type login --email [email protected] --password yourpass. The token is stored in your WebSocket session automatically.

For the HTTP API

# Get a token
TOKEN=$(curl -s -X POST https://nemlai.milops.org/cli/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "pass"}' \
  | grep TOKEN | awk '{print $2}')

# Use it
curl https://nemlai.milops.org/cli/api/whoami \
  -H "Authorization: Bearer $TOKEN"

For the Python SDK

# Login returns a client with token
client = NemlAI.login("email", "password")

# Or reuse a saved token
client = NemlAI(token="nemlai_...")

For AI Agents

The CLI is designed to be easy for autonomous agents to use:

• Every response starts with STATUS: ok or STATUS: error — easy to parse
• Error messages include HINT lines with the exact command to fix the issue
• The generic /cli/api/command endpoint accepts free-text commands
• No HTML, no JSON — just plain text that's readable and parseable
• The Python SDK provides typed methods if you prefer structured access

Recommended agent flow

# 1. Check health
curl https://nemlai.milops.org/cli/api/health

# 2. Log in once, save the token
curl -X POST https://nemlai.milops.org/cli/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "...", "password": "..."}'

# 3. Generate a basket
curl -X POST https://nemlai.milops.org/cli/api/basket/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"size": "medium", "date": "2026-03-15"}'

# 4. Review and adjust items
curl https://nemlai.milops.org/cli/api/basket/items \
  -H "Authorization: Bearer $TOKEN"

# 5. Send to Nemlig
curl -X POST https://nemlai.milops.org/cli/api/basket/send \
  -H "Authorization: Bearer $TOKEN"