GoList Shared-List Manager (OpenClaw Skill)

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 <share-token-uuid>

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 <token>
• “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.