GoList

GoList Shared-List Manager (OpenClaw Skill)

Purpose

Enable OpenClaw to manage GoList through a simple, beginner-friendly CLI wrapper around the backend API.

GoList is a simplistic app for creating and sharing grocery / shopping lists. This skill is designed to make first-time usage feel fast and approachable: create a list, add items, share with others, and switch between saved lists with minimal setup.

This skill supports:

creating new lists,

joining shared lists via share token,

saving known lists (name + id) and switching between them,

generating share tokens for users,

reading lists,

upserting items,

soft-deleting items.

Hard constraints

1. API base URL is fixed to https://go-list.app/api and must never be overridden. 2. OpenClaw must generate its own random device UUID and persist it for reuse. 3. Every request must include the X-Device-Id header. 4. For item writes, OpenClaw must only set: - name (required), - deleted (optional, defaults to false), - quantityOrUnit (optional). 5. OpenClaw must generate all item UUIDs and timestamps in the Python CLI (never require the agent to provide them). 6. Immediately after creating a new list, OpenClaw must always generate a share token and send the share URL to the user without being asked. 7. When talking to the user, OpenClaw must never refer to lists by ID; always use list names (use the stored name↔id mapping internally). 8. For item upserts, if the user does not explicitly provide a quantity/unit, OpenClaw must omit quantityOrUnit.

Python CLI tool

Use apps/openclaw/golist_cli.py as the operational API wrapper for this skill.

CLI guarantees

Fixed API base URL: https://go-list.app/api.

Generates and persists device id when missing.

Generates list IDs and item IDs when creating entities.

Generates item updatedAt timestamps on write operations.

Automatically sends X-Device-Id on every request.

Persists known lists with friendly names and IDs, and tracks an active list.

CLI state and environment

Optional environment:

GOLIST_DEVICE_ID (override persisted device id)

OPENCLAW_STATE_FILE (custom path for persisted JSON state)

GOLIST_SHARE_TOKEN (optional token source for bootstrap --share-token)

Persisted state file (default):

~/.openclaw_golist_state.json with:

- device_id - active_list_id - known_lists[] containing id + name

Core flows

1) Create a new list

python3 apps/openclaw/golist_cli.py create-list "Weekend groceries"
python3 apps/openclaw/golist_cli.py share

Creates a list with a generated UUID, stores it in known lists, sets it as active, then immediately creates a share token and returns the share URL to the user.

2) Share a list with a user

python3 apps/openclaw/golist_cli.py share

Creates a share token for the active list and returns both token + share URL.

3) Join an existing list via share token

python3 apps/openclaw/golist_cli.py join 

Redeems the token, fetches the real list name from the API, stores that name+id mapping, and sets it active.

4) Switch/access saved lists

python3 apps/openclaw/golist_cli.py lists
python3 apps/openclaw/golist_cli.py use-list "Weekend groceries"
python3 apps/openclaw/golist_cli.py show

5) Item writes (restricted fields)

python3 apps/openclaw/golist_cli.py upsert "milk" [--quantity "2 L"] [--deleted]
python3 apps/openclaw/golist_cli.py delete "milk"

Intent mapping for OpenClaw

“create a new list called X” → create-list "X"

After create-list, always run share and send the URL/token to the user.

“share this list with me” → share

“join this token” → join

“show my lists” → lists

“switch to list X” → use-list "X"

“show current list” → show

“add X (qty)” → upsert "X" [--quantity "..."]

“remove X” → delete "X"

Safety behavior

If device id is missing, generate and persist it before any API call.

If no active list is set, require create-list or join first.

If token redemption fails, return a clear auth/share error.

In user-facing responses, refer to lists by name only (never by raw ID).

Do not invent item quantities; only send --quantity when the user asked for one.

Never send item metadata fields outside name, deleted, and optional quantityOrUnit.