feat(alexandria): default search to web, alexandria, and skills (1.28.1)

DE
5d ago
+2223-99

Updates the Alexandria CLI for the latest Exchange changes and bumps the package to 1.28.1. With an API key and no --sources, search sends web, alexandria, and skills. Main already published 1.28.0, so this release note moved forward. This does not publish to npm or tag a release. Rebased onto current main.

Commands and flags

The skills surface is four operations: list, read, create, and update. skills list|read|create|update are the same commands as find-skills, read-skill, create-skill, and update-skill.

  • find-tools retries once when the scrape returns HTTP 503 query_embed_unavailable. It waits for Retry-After and never longer than 3 seconds, reuses the same request id, and if the second attempt fails prints retryable: true with a message to run the command again.
  • There is no sharing option. skills create sends from, name, description, body, and slug. skills update sends id, baseVersion, name, description, body, enabled, and discoverable. Both accept --body-file in place of --body and --request-id to retry the same save. --enabled and --discoverable turn a skill off or hide it. There is no delete, and no Exchange route was added for sharing.
  • A successful skills create or skills update prints https://www.firecrawl.dev/app/alexandria/skills/<slug>, using the slug without the team: prefix, and includes that link as url in --json. Exchange sharePath (/skills/s/<publicId>) is not used.
  • skills list takes a natural-language goal. Official and provider skills are ranked semantically; team skills still match every word. --provider <provider> sends provider, q, and page and follows pages until the catalogue is covered (including when Exchange omits total). It matches provider.slug and plugin.id and does not re-filter the server's ranking by literal words. A named provider includes the execution-only skills Exchange returns for it. The unfiltered catalogue does not call the provider-skills endpoint.
  • skills read reads a Firecrawl or team skill by id. --provider, --plugin, and --skill read a provider skill; --file reads its file (GET /exchange/provider-skills/:provider/:plugin/:skill/file).
  • search accepts skills in --sources. With an API key and no --sources, it sends web, alexandria, and skills. An explicit --sources list is used as given (alexandria is still added when a key is set). A search without a key does not add skills. When the response includes data.skills (id, name, description, source official or provider, optional provider slug, similarity), search prints a Skills section after web results and tools. Official and team cards hint firecrawl skills read <id>. Provider cards hint firecrawl skills read --provider <provider> --plugin <plugin> --skill <skill>. --json includes the same cards. A response without data.skills is unchanged.
  • No --async flag. People Data Labs async enrichment stays execution-only.

Provider skills are forwarded

apps/api in firecrawl/firecrawl does forward them. GET and PATCH /exchange/provider-skills{/*path} proxy to Exchange /v1/provider-skills (FORWARDED_PATH_ROOTS, Labs rate limit, no exchangeRetrieve requirement; firecrawl/firecrawl#5487). POST, PUT, and DELETE are not registered. The CLI only lists and reads, so it uses GET. Search skill cards use POST /v2/search with source skills (firecrawl/firecrawl#5560).

Prices

src/utils/alexandria-prices.ts records merged execution prices:

  • Carbon Arc: 1000 credits per call.
  • Influencers.club: the live capability schedule (connected socials 165 per call, search 45 per creator returned or 56 with return_filter_values, similar creators 50, audience overlap and full enrich 330, and the remaining enrich, content, and free dictionary lookups).
  • People Data Labs (#1144, now merged): person/enrich and person/identify 60 per successful call; person/search, person/bulk, company/search, and company/bulk 50 per returned or matched record; company/enrich 50 per successful call; preview, IP enrich, and jobs endpoints 1; cleaners and autocomplete 0. Misses are free.

list and find-tools fill a missing discovery price from that catalog when --include-costs is set. search always omits tool prices.

Tests

Integration coverage is in src/__tests__/alexandria-beta.test.ts (retry cap, unknown --shared rejected, --enabled and --discoverable on update, the app skill link on create and update, --provider query and paging against the live object shape, paging when total is omitted, provider read with --file, default skills on search). Search skill cards, the default source list, and the list-query help are in src/__tests__/commands/search.test.ts. Price and helper checks are in src/__tests__/utils/alexandria-prices.test.ts.

Open in Web Open in Cursor 

Summary by cubic

Updates the Alexandria CLI for the latest Exchange changes and bumps the package to 1.28.1 without publishing to npm or tagging a release. With an API key and no --sources, search now sends web, alexandria, and skills.

Skills

  • Merging main retires the github search category and research search-github; 2xx Exchange envelopes reporting success false are now treated as errors across skill and tool calls.
  • find-tools retries once on HTTP 503 query_embed_unavailable, honoring Retry-After capped at 3 seconds and reusing the request id; a second failure prints retryable: true. The printed request id is also sent as X-Request-ID.
  • With an API key, search sends web, alexandria, and skills unless --sources is set; an explicit list is kept as given, and a keyless search adds nothing. A discovery refusal retries only when every discovery source was added by the CLI.
  • skills list takes a natural-language goal and lists provider-published skills with --provider, including execution-only skills, capping results at 20 by default. It handles flat and grouped payloads, keeps paging when Exchange omits total, and keeps provider skills without an id; team skills still match every word.
  • read-skill reads a provider skill with --provider, --plugin, and --skill, or its file with --file, and fails when the file cannot be loaded.
  • create-skill and update-skill send from/name/description/body/slug and id/baseVersion/enabled/discoverable; Exchange accepts no sharing option, and --enabled false or --discoverable false turn a skill off or hide it. A successful save prints the app skill page, included as url in --json.
  • search prints a Skills section after web results and tools when data.skills is present and includes it in --json; the skill id line and the read hint print only when the card has an id. Read hints quote provider, plugin, skill, and id values that are not plain tokens. A response without skills is unchanged.

Retries and prices

  • Merged prices record Carbon Arc (1000 per call), Influencers.club (per-capability, 56 for search with return_filter_values, 20 for a TikTok transcript), and People Data Labs (misses free). list and find-tools fill missing discovery prices from the catalog with --include-costs; search always omits tool prices. People Data Labs async enrichment stays execution-only and has no flag.