AFOL Rebrickable

Use the Rebrickable API through the included CLI for LEGO catalog lookup, user set/part lists, build analysis, lost parts, and guarded collection writes.

Rebrickable AFOL skill

Use this skill when the user asks for Rebrickable catalog lookup, Rebrickable set or part list management, user collection analysis, buildability checks, minifigs from owned sets, all-parts inventory, or lost-parts tracking.

Primary interface: scripts/rebrickable.

The skill is self-contained for archive distribution and wraps the Rebrickable API directly using checked-in references inside this skill directory:

• OpenAPI reference: references/openapi/rebrickable.yaml
• Domain guidance: references/prompts/rebrickable-tools.txt
• CLI source: scripts/rebrickable_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.

Authentication

Required environment variable:

bash

export REBRICKABLE_API_KEY=...

Optional environment variables:

bash

export REBRICKABLE_USER_TOKEN=...       # needed for user collection endpoints
export REBRICKABLE_BASE_URL=https://rebrickable.com/api/v3

Never print, commit, log, or paste real API keys or user tokens. Commands should reference credentials only indirectly through the CLI.

Rebrickable auth placement matters: API authentication goes in the Authorization header as key <REBRICKABLE_API_KEY>. The CLI handles that header and redacts it in dry runs.

User-specific endpoints include the user token in the URL path. Treat REBRICKABLE_USER_TOKEN as private even though it is not the API key.

CLI quick reference

Run commands from this skill directory:

bash

scripts/rebrickable --help
scripts/rebrickable colors --page-size 5
scripts/rebrickable sets --search "Millennium Falcon" --page-size 5
scripts/rebrickable set --set-num 75192-1
scripts/rebrickable set-parts --set-num 75192-1 --page-size 20
scripts/rebrickable parts --part-num 3001
scripts/rebrickable element --element-id 300121
scripts/rebrickable minifigs --search "Darth Vader" --page-size 5
scripts/rebrickable part-categories --page-size 20
scripts/rebrickable themes --page-size 20

User read-only examples, only when REBRICKABLE_USER_TOKEN is configured or passed with --user-token:

bash

scripts/rebrickable profile
scripts/rebrickable set-lists
scripts/rebrickable set-list-sets --list-id 123
scripts/rebrickable all-sets --search "Star Wars" --page-size 20
scripts/rebrickable part-lists
scripts/rebrickable part-list-parts --list-id 456 --page-size 20
scripts/rebrickable all-parts --part-num 3001 --page-size 20
scripts/rebrickable all-minifigs --search "astromech" --page-size 20
scripts/rebrickable build --set-num 8043-1
scripts/rebrickable lost-parts --page-size 20

Mutating commands are guarded. They do nothing unless passed --yes; use --dry-run first:

bash

scripts/rebrickable create-set-list --dry-run --name "Wanted builds" --is-buildable true
scripts/rebrickable add-sets-to-list --dry-run --list-id 123 --sets-json '[{"set_num":"8043-1","quantity":1}]'
scripts/rebrickable update-set-in-list --dry-run --list-id 123 --set-num 8043-1 --quantity 2
scripts/rebrickable remove-set-from-list --dry-run --list-id 123 --set-num 8043-1
scripts/rebrickable create-part-list --dry-run --name "Missing dark bluish gray"
scripts/rebrickable add-part-to-list --dry-run --list-id 456 --part-num 3001 --color-id 72 --quantity 4
scripts/rebrickable update-part-in-list --dry-run --list-id 456 --part-num 3001 --color-id 72 --quantity 8
scripts/rebrickable remove-part-from-list --dry-run --list-id 456 --part-num 3001 --color-id 72
scripts/rebrickable add-lost-part --dry-run --inv-part-id 806698 --lost-quantity 1
scripts/rebrickable remove-lost-part --dry-run --lost-part-id 999

Safety rules

Read-only by default:

• public catalog commands: colors, color, element, minifigs, minifig, minifig-parts, minifig-sets, part-categories, part-category, parts, part, part-colors, part-color, part-color-sets, sets, set, set-parts, set-minifigs, set-alternates, themes, theme
• user read commands: profile, set-lists, set-list, set-list-sets, all-sets, part-lists, part-list-parts, all-parts, all-minifigs, build, lost-parts

Mutating operations require explicit user confirmation in the current conversation before execution:

• create-set-list, update-set-list, delete-set-list
• add-sets-to-list, update-set-in-list, remove-set-from-list
• create-part-list, delete-part-list
• add-part-to-list, update-part-in-list, remove-part-from-list
• add-lost-part, remove-lost-part

Stored credentials are not permission. Before any mutation, restate the exact platform, list ID, set number, part number, color ID, quantity, lost-part record, and whether the operation creates, updates, or deletes data. Wait for explicit confirmation such as "yes, add set 8043-1 to Rebrickable list 123".

The CLI enforces this mechanically: mutating commands fail unless --yes is passed, and --dry-run prints the request shape with the Authorization header and REBRICKABLE_USER_TOKEN path segment redacted.

If the user asks to "add to my collection" or "show my collection" without naming a platform and Brickset/Rebrickable are both configured, ask which service to use before mutating or reading private collection data. If they explicitly name Rebrickable, use only Rebrickable.

Endpoint coverage

Catalog coverage:

• GET /lego/colors/ and GET /lego/colors/{id}/
• GET /lego/elements/{element_id}/
• GET /lego/minifigs/, GET /lego/minifigs/{set_num}/, GET /lego/minifigs/{set_num}/parts/, GET /lego/minifigs/{set_num}/sets/
• GET /lego/part_categories/ and GET /lego/part_categories/{id}/
• GET /lego/parts/, GET /lego/parts/{part_num}/, GET /lego/parts/{part_num}/colors/, GET /lego/parts/{part_num}/colors/{color_id}/, GET /lego/parts/{part_num}/colors/{color_id}/sets/
• GET /lego/sets/, GET /lego/sets/{set_num}/, GET /lego/sets/{set_num}/parts/, GET /lego/sets/{set_num}/minifigs/, GET /lego/sets/{set_num}/alternates/
• GET /lego/themes/ and GET /lego/themes/{id}/

User coverage:

• GET /users/{user_token}/profile/
• GET/POST /users/{user_token}/setlists/
• GET/PATCH/DELETE /users/{user_token}/setlists/{list_id}/
• GET/POST /users/{user_token}/setlists/{list_id}/sets/
• GET/PATCH/DELETE /users/{user_token}/setlists/{list_id}/sets/{set_num}/
• GET /users/{user_token}/sets/
• GET /users/{user_token}/partlists/
• POST /users/{user_token}/partlists/
• DELETE /users/{user_token}/partlists/{list_id}/
• GET/POST /users/{user_token}/partlists/{list_id}/parts/
• PUT/DELETE /users/{user_token}/partlists/{list_id}/parts/{part_num}/{color_id}/
• GET /users/{user_token}/parts/
• GET /users/{user_token}/allparts/
• GET /users/{user_token}/minifigs/
• GET /users/{user_token}/build/{set_num}/
• GET/POST /users/{user_token}/lost_parts/
• DELETE /users/{user_token}/lost_parts/{id}/

Treat set-list names, part-list names, owned sets, part inventories, build analysis, lost parts, emails, and profile data as private. Summarize only what the user needs.

Known Rebrickable endpoint quirks

Use sets --search for fuzzy set lookup, but use set --set-num when the user gives an exact Rebrickable set number:

bash

scripts/rebrickable set --set-num 75192-1
scripts/rebrickable sets --search "Millennium Falcon" --page-size 5

When adding sets to a set list, Rebrickable requires a JSON array even for a single set. The CLI validates this before sending the request:

bash

scripts/rebrickable add-sets-to-list --dry-run --list-id 123 --sets-json '[{"set_num":"8043-1","quantity":1}]'

The all-parts endpoint is explicitly resource-intensive in the checked-in OpenAPI reference. Use filters such as --part-num, --part-cat-id, --color-id, and small --page-size values whenever possible.

update-set-in-list updates only the specified set in the specified list. Rebrickable also has broader /users/{user_token}/sets/{set_num}/ semantics that can create or delete based on quantity; this CLI intentionally does not expose that broader mutation because it is too easy to misuse.

Live smoke checks

Only run live smoke checks when REBRICKABLE_API_KEY is configured. Summarize response shape only, never private field values.

Public read-only smoke:

bash

scripts/rebrickable sets --search "Millennium Falcon" --page-size 1

Optional private read-only smoke, only when REBRICKABLE_USER_TOKEN is configured and the user context permits private collection reads:

bash

scripts/rebrickable profile
scripts/rebrickable set-lists --page-size 1

Do not run mutation smoke tests against the live API. Use --dry-run for write-shape verification.

Verification

Local, no-network checks:

bash

python3 -m py_compile scripts/rebrickable_cli.py
scripts/rebrickable add-sets-to-list --dry-run --user-token dummy --list-id 123 --sets-json '[{"set_num":"8043-1","quantity":1}]'
python3 -m unittest discover -s tests -p 'test_*.py'
scripts/validate-skills.sh
git diff --check