Command API Mapping

Command → API mapping

Build the data/command-api-mapping/<COMMAND>.json files that drive the per-command

"API methods" tables in the docs. Each file lists, for one Redis command, the equivalent

method signature(s) in each client library.

This is AI-in-the-loop work, not a pure extractor. Reading a client's source file and

turning it into a correct mapping row needs judgment a parser can't supply (public method

name vs. internal function, return type buried in wrappers, descriptions that aren't in the

source at all). You do that judgment; the reference files give you the durable facts.

> Background: an MCP server under build/command_api_mapping/ (underscore) was an earlier,

> heavier attempt at this. It is not wired into the live pipeline and you don't need it.

> The live pipeline is the per-command JSON files + the merge script described below.

When to use

• Adding a new command family to the mapping (the array AR* commands, a new module).
• Refreshing one client's signatures after an API change.
• Filling gaps where a command is missing a client that actually supports it.

The pipeline (how output is consumed)

• Source of truth: one file per command at data/command-api-mapping/<COMMAND>.json

(e.g. ARSET.json, BF.ADD.json). Filename = command name, including any space

(e.g. ACL CAT.json).

• Merge: ./build/merge-command-api-mapping.sh concatenates all per-command files into

data/command-api-mapping.json.

• Overrides: data/command-api-mapping-overrides.json *replaces* (not merges) entries

when the auto-generated data is wrong and you can't fix it at the source.

• Render: layouts/partials/components/api-methods-tab.html and

layouts/partials/commands-foldout.html read the merged file.

See reference/output-schema.md for the exact JSON shape and the full client-ID list.

Workflow

For each command in the set you're mapping:

• Identify the target clients. Only include clients that actually ship the command.

For preview/unreleased commands, a client may have it only on master — note that and

decide per task whether to include it. (See reference/client-source-map.md for repos,

IDs, and default branches.)

• Locate the source file(s). Use the per-client source map in

reference/client-source-map.md. It can be stale for brand-new commands — the map is

a starting point, not gospel. To find where a new command lives, list the client's command

directory via the GitHub contents API (recipe in the source map reference). This is the

step that caught us out on AR*: the array files existed but weren't in any map.

• Read the source and extract the real signature. Read the file directly. For each

relevant method capture: public method name, parameters (name + type, skipping

context/self/internal params), and return type. Apply the per-client translation rules

in reference/client-quirks.md — these encode the non-obvious bits (e.g. node-redis method

name = camelCase of the filename, return type lives in transformReply, and there are no

doc comments).

• Write descriptions. Source doc comments are the first choice. Where a client has none

(node-redis, often go-redis), leave description: "" — do not invent prose. The

command's own reference page already carries the human explanation; the table only needs

the signature shape.

• Write the per-command file at data/command-api-mapping/<COMMAND>.json in the exact

schema (see reference/output-schema.md). Multiple overloads → multiple objects in the

client's array. Omit clients that don't have the command.

• Merge and verify:

   ./build/merge-command-api-mapping.sh
   python3 -c "import json; json.load(open('data/command-api-mapping.json'))"  # valid JSON

Spot-check one command in the rendered table if you can run the site.

Guardrails

• Match the live client IDs exactly, including go-redis (hyphen) and node_redis,

redis_py (underscores). Wrong IDs render nothing. Full list in reference/output-schema.md.

• Don't fabricate signatures or descriptions. If you can't confirm a client has a command,

omit that client rather than guess.

• Network: fetching client source uses raw.githubusercontent.com / the GitHub API. The

default command sandbox blocks these hosts — run fetches with the sandbox disabled (or use

/sandbox to allow them).

• Improve this skill as you go. When you hit a new quirk or a stale source path, update the

relevant reference file so the next run is cheaper.

Reference files

• reference/output-schema.md — exact per-command JSON schema, file locations, merge script,

overrides, client-ID list, consumers.

• reference/client-source-map.md — per-client repos, default branches, and the known source

file locations for command definitions; recipe for finding new command files.

• reference/client-quirks.md — per-client translation rules for turning source into a

mapping row (naming, return types, doc-comment availability, internal params to strip).