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:

export REBRICKABLE_API_KEY=...

Optional environment variables:

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:

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:

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:

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:

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:

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:

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:

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:

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