AFOL BrickLink

use this skill when the user asks for bricklink item lookup, price guides, known colors, images, supersets, subsets, item mapping, orders, inventory, feedback, coupons, notifications, shipping methods, member ratings, or private member notes.

primary interface: scripts/bricklink.

the skill is self-contained for archive distribution and wraps the bricklink api directly using checked-in references:

• openapi reference: references/openapi/bricklink.yaml
• domain guidance: references/prompts/bricklink-tools.txt
• cli source: scripts/bricklink_cli.py

do not scrape vendor docs or invent parameters when the checked-in openapi reference covers the endpoint. if the reference is insufficient, say what is missing.

intent

query bricklink's catalog, pricing, orders, inventory, feedback, coupons, shipping, notifications, and member notes via oauth1-signed api calls. use this when the user needs read-only lookups (item details, price guides, order history, ratings) or guarded writes (inventory mutations, feedback, coupons, member notes). reads are instant; writes require explicit user confirmation and --yes flag.

inputs

required environment variables (oauth1 credentials):

• BRICKLINK_API_CONSUMER_KEY: oauth consumer key from bricklink app settings.
• BRICKLINK_API_CONSUMER_SECRET: oauth consumer secret.
• BRICKLINK_API_TOKEN_VALUE: oauth token value for your bricklink account.
• BRICKLINK_API_TOKEN_SECRET: oauth token secret.

optional override:

• BRICKLINK_API_BASE_URL: defaults to https://api.bricklink.com/api/store/v1. change only if bricklink moves or you use a test endpoint.

never print, commit, log, or paste the real oauth credentials. commands reference BRICKLINK_API_* variables only indirectly through the cli.

external connection:

• bricklink api (https://api.bricklink.com/api/store/v1). requires live internet. oauth1.0a authorization: oauth ... header auth, not query params or body creds.

checked-in cli and references:

• scripts/bricklink_cli.py: handles oauth signing, request dispatch, response parsing.
• references/openapi/bricklink.yaml: endpoint definitions, parameter bounds, response schemas.

procedure

1. inspect bricklink cli help

input: none. output: cli command list, argument syntax.

scripts/bricklink --help

2. run read-only queries (catalog, item, price, order, inventory, feedback, notifications, coupons, shipping, member data)

input: command name, flags (e.g., --type SET --no 75192-1, --order-id 123456, --username example_user). output: json response from bricklink api, pretty-printed or raw.

examples:

scripts/bricklink colors
scripts/bricklink color --color-id 11
scripts/bricklink categories
scripts/bricklink item --type SET --no 75192-1
scripts/bricklink item-price --type SET --no 75192-1 --guide-type sold --new-or-used N --currency-code EUR
scripts/bricklink item-colors --type PART --no 3001
scripts/bricklink item-mapping --type PART --no 3001 --color-id 5
scripts/bricklink element-mapping --element-id 4211111
scripts/bricklink inventory-list --item-type SET --status Y
scripts/bricklink orders --direction in --status PAID
scripts/bricklink order --order-id 123456
scripts/bricklink order-items --order-id 123456
scripts/bricklink order-messages --order-id 123456
scripts/bricklink order-feedback --order-id 123456
scripts/bricklink notifications
scripts/bricklink coupons
scripts/bricklink coupon --coupon-id 987654
scripts/bricklink shipping-methods
scripts/bricklink shipping-method --method-id 1
scripts/bricklink member-ratings --username example_user
scripts/bricklink member-notes --username example_user
scripts/bricklink feedback
scripts/bricklink feedback-view --feedback-id 555555

read-only commands never touch live state. safe to run anytime.

3. preview a mutating write with --dry-run (no credentials sent, no network call)

input: command name, flags, --dry-run flag, --json payload for create/update/delete operations. output: redacted request shape (credentials shown as env var names, not values), response shape, no side effects.

examples:

scripts/bricklink inventory-create --dry-run \
  --json '{"item":{"type":"PART","no":"3001"},"color_id":5,"quantity":1,"unit_price":"0.12","new_or_used":"U"}'

scripts/bricklink inventory-update --dry-run --inventory-id 123456 \
  --json '{"quantity":2,"unit_price":"0.15"}'

scripts/bricklink inventory-delete --dry-run --inventory-id 123456

scripts/bricklink order-status --dry-run --order-id 123456 --json '{"status":"PACKED"}'

scripts/bricklink feedback-create --dry-run --json '{"order_id":123456,"rating":"POSITIVE","comment":"Thank you"}'

scripts/bricklink feedback-reply --dry-run --feedback-id 555555 --json '{"comment":"Thanks for the feedback"}'

scripts/bricklink coupon-create --dry-run --json '{"buyer_name":"example_user","discount_rate":5}'

scripts/bricklink coupon-update --dry-run --coupon-id 987654 --json '{"discount_rate":10}'

scripts/bricklink coupon-delete --dry-run --coupon-id 987654

scripts/bricklink member-notes-update --dry-run --username example_user --json '{"note":"Asked about train parts"}'

scripts/bricklink member-notes-delete --dry-run --username example_user

4. confirm the exact action with the user

input: dry-run output summary (target id, item, payload fields). output: user says "yes, do it" or "cancel".

restate:

• endpoint (e.g., PUT /inventories/123456).
• resource (e.g., "bricklink inventory lot 123456").
• action (e.g., "update quantity to 2, price to 0.15 EUR").
• whether action is destructive (deletes are permanent).
• exact payload (feedback text, coupon discount rate, order status, member note).

do not run the mutation until you see explicit yes from the user (e.g., "yes, update", "confirm", "do it").

5. execute the mutation with --yes flag

input: command name, flags, --json payload, --yes flag. output: http status, response body (inventory id, order status, coupon id, feedback id, etc.), or error.

examples:

scripts/bricklink inventory-create --yes --json "$INVENTORY_JSON"

scripts/bricklink inventory-update --yes --inventory-id 123456 --json "$PATCH_JSON"

scripts/bricklink inventory-delete --yes --inventory-id 123456

scripts/bricklink order-status --yes --order-id 123456 --json "$STATUS_JSON"

scripts/bricklink feedback-create --yes --json "$FEEDBACK_JSON"

scripts/bricklink coupon-create --yes --json "$COUPON_JSON"

scripts/bricklink member-notes-update --yes --username example_user --json "$NOTE_JSON"

6. verify the change (read-only check)

input: resource id (inventory-id, order-id, coupon-id, username, etc.). output: current state of the resource.

examples:

scripts/bricklink inventory --inventory-id 123456
scripts/bricklink order --order-id 123456
scripts/bricklink coupon --coupon-id 987654
scripts/bricklink member-notes --username example_user

7. run smoke checks (before skill deployment)

input: none (local, no network). output: python syntax valid, all tests pass, no trailing whitespace.

python3 -m py_compile scripts/bricklink_cli.py
scripts/bricklink inventory-delete --dry-run --inventory-id 123456
python3 -m unittest discover -s tests -p 'test_*.py'
scripts/validate-skills.sh
git diff --check

optional: read-only network check (only if all four BRICKLINK_API_* are set):

scripts/bricklink colors

summarize only response shape (status, top-level keys, rough counts). never paste account, order, inventory, member-note data or credential values.

decision points

if user asks for a read-only query (item, price, order, feedback, notification, coupon, shipping, member ratings): run the read-only command directly. no confirmation needed. safe to execute immediately.

if user asks to create, update, or delete inventory, order status, feedback, coupon, or member note: first, check that all four BRICKLINK_API_* env vars are set. if any are missing, stop and tell the user which vars are missing. if set, draft the exact json payload, run --dry-run, show the output to the user, and wait for explicit confirmation ("yes", "confirm", "do it") before running --yes.

if user says "sell item", "list lot", "update my store", "delete inventory", "leave feedback", or "create coupon" but does not name a platform and both bricklink and brickowl are available in the conversation context: ask which marketplace (bricklink or brickowl) before touching anything. do not guess.

if user asks for a price estimate and does not specify guide-type, new-or-used, or currency: set defaults explicitly: --guide-type sold (not stock), --new-or-used N (new, unless the user asks for used), --currency-code EUR (or user's currency). show the user the defaults you chose before running the query.

if user asks for item supersets or subsets and does not mention breaking minifigs or subsets: ask whether to break them (e.g., "should i expand minifigs into parts?" or "keep sets as-is?") before fetching. these flags change response shape.

if the user asks for large price breakdowns (e.g., "get prices for all 600 parts in set X"): ask for approval first. price fan-out can generate many api calls and hit rate limits. show the count and scope before executing.

if a read-only query returns an empty result set (no colors, no orders, no feedback, no coupons, no inventory): report the empty state clearly. do not retry or invent dummy data. empty is valid.

if the bricklink api returns a 401, 403, or invalid-signature error: the credentials are wrong or expired. tell the user to check all four BRICKLINK_API_* env vars, re-auth in bricklink account settings, and regenerate tokens if needed.

if the bricklink api is slow (>5 second response) or times out: report the latency or timeout. do not auto-retry. ask the user whether to retry manually. bricklink may be under load.

if the user tries to delete an inventory lot, order, coupon, or member note: require immediate confirmation with the exact resource id and a plain-language summary of what will be deleted. deletions are permanent. do not proceed without explicit yes.

output contract

success means:

• for read-only queries: json response matches bricklink api schema. keys present: price_guide (price queries), color_id (item with colors), order_id (order queries), etc. http status 200. no errors.
• for dry-run mutations: redacted json request (creds as env var names), response shape, no network calls, exit code 0.
• for executed mutations with --yes: http status 200 or 201, response body includes created/updated resource id, timestamp, or confirmation flag. no errors.
• for deletes: http status 204 (no content) or 200 with confirmation. resource no longer queryable in a follow-up read.

data format:

• responses are json. cli pretty-prints by default.
• inventory payloads: {"item":{"type":"PART"|"SET"|"MINIFIG","no":"<part-no>"},"color_id":5,"quantity":1,"unit_price":"0.12","new_or_used":"N"|"U","description":"...","remarks":"..."}.
• order status: {"status":"PAID"|"PROCESSING"|"PACKED"|"SHIPPED"|"RECEIVED"}.
• feedback: {"order_id":123456,"rating":"POSITIVE"|"NEUTRAL"|"NEGATIVE","comment":"..."}.
• coupon: {"buyer_name":"username","discount_rate":5} (5 = 5% off).
• member note: {"note":"custom text"}.

no private account numbers, real order ids, inventory ids, or member usernames are written to logs or stdout during normal operation. --dry-run redacts credentials.

file locations:

• cli: scripts/bricklink or scripts/bricklink_cli.py.
• openapi spec: references/openapi/bricklink.yaml.
• tests: tests/test_*.py.

outcome signal

the user knows the skill worked when:

• read-only query: the response includes the requested data (item details, price range, order summary, feedback count, coupon discount, shipping method, member rating, etc.). no errors in stderr. command exits with code 0.
• dry-run: the cli shows a redacted request (credentials masked as $BRICKLINK_API_TOKEN_VALUE, etc.), the request shape, and exits with code 0. no network call was made.
• mutation with --yes: the cli returns http 200 or 201, the response includes the resource id (inventory-id, coupon-id, etc.), a timestamp, or a success flag. the user can then run a read-only query to verify the change (e.g., inventory --inventory-id 123456). no errors.
• delete with --yes: the cli returns http 204 or 200, a follow-up read query for the same resource returns 404 or empty. the lot, coupon, note, etc. is gone.
• confirmation loop: before any mutation, the user sees the exact target id, payload fields, and action described in plain language. the user has a chance to cancel or approve. no write happens without explicit yes.

if the skill fails:

• http error (4xx, 5xx): stderr shows the status, error message, and request details (without credential values). tell the user to check the request and retry.
• missing env vars: stderr lists which BRICKLINK_API_* vars are not set. user must export them and retry.
• dry-run exits with code 0 but shows warnings: the request shape is valid but the payload may be incomplete. ask the user to add missing fields.
• timeout or network error: stderr says the bricklink api is unreachable. ask the user to check internet and try again.