add-command

---
name: add-command
description: Use when adding a new Redis command (or RediSearch / TimeSeries / VectorSet / module subcommand) to go-redis — covers fetching the command spec and docs, the Cmder type, Cmdable interface wiring, RESP parsing, tests, and the custom-vet rule that enforces SetVal.
allowed-tools: WebFetch
---

# Adding a new Redis command

Router for adding a Redis command to the root `redis` package. Read the reference file for the area you're touching — don't load all of them.

## Step 0 — Get the command spec AND docs FIRST

Before writing any Go, know the exact command shape (arguments, optional flags, reply structure, since-version, key positions) **and** its documented semantics (what each reply field means, RESP2-vs-RESP3 differences, examples). Fetch **two** sources — the machine-readable spec and the prose docs. They cover different gaps: the spec nails arguments and key positions, the docs nail what the reply actually looks like.

### A. Machine-readable spec (arguments, key specs, reply schema)

Resolve the spec in this order:

1. **Spec file argument** — if the user passed a path to a spec/JSON file, read it.
2. **PR URL argument** — if the user passed a `github.com/redis/redis` PR (or other repo) URL, fetch the diff and read the command definition + `src/commands/<cmd>.json` it adds.
3. **No argument** — fetch the machine-readable spec from redis/redis:
   ```
   https://raw.githubusercontent.com/redis/redis/unstable/src/commands/<command>.json
   ```
   Container subcommands use `<container>-<sub>.json` (e.g. `client-info.json`). **A 404 means it's a module command** (RediSearch, TimeSeries, VectorSet, Bloom) — those specs live in the **module's own repo**, not redis/redis. Switch to the module repo (see `references/module-commands.md` §1) or ask the user for the spec/PR. Don't retry the redis/redis URL.

### B. Prose docs (semantics, return value, RESP2/RESP3 reply, examples)

The JSON `reply_schema` is often thin or missing; the docs spell out what the reply actually is — including separate **RESP2 Reply** and **RESP3 Reply** sections, which decide your `readReply` and any module RESP2-vs-RESP3 handling. Fetch the command's doc page:

```
https://redis.io/docs/latest/commands/<command>/
```

Raw markdown source (alternative, good for diffing or when the rendered page is noisy):
`https://raw.githubusercontent.com/redis/redis-doc/master/commands/<command>.md`.
**Module commands** (RediSearch, TimeSeries, …) are documented under their own
path on redis.io (e.g. `/docs/latest/commands/ft.search/`) or in the module repo
— see `references/module-commands.md`.

Read the **Return value / RESP2 Reply / RESP3 Reply** sections plus the examples, and reconcile them against the JSON `reply_schema`. When the two disagree, the docs' reply description (and a quick `redis-cli` check) win.

### Map both sources to the implementation

| Source | Drives |
|--------|--------|
| spec `arguments` | method signature, args-slice build order, optional `FooArgs` struct |
| spec `reply_schema` + docs **Return value** | the `readReply` parser and Cmder result type |
| docs **RESP2 Reply / RESP3 Reply** | RESP2-vs-RESP3 branching in `readReply` (see `references/module-commands.md`) |
| spec `since` + docs `@history` | `SkipBeforeRedisVersion(...)` in the integration test, doc comment |
| spec `key_specs` | key-position maps in `command.go`; cluster routing |
| spec `command_flags` (e.g. `READONLY`, no key) | keyless / fan-out handling, cluster routing |
| docs examples | integration-test cases and expected values |

If you can't get either source, STOP and ask the user — guessing the reply shape produces a broken `readReply`.

## Decide before you start

1. **Which `*_commands.go` file?** — pick the existing file matching the data type (`string_commands.go`, `hash_commands.go`, `search_commands.go`, …). Only create a new file for a genuinely new category. New files need a matching `XxxCmdable` interface embedded in `Cmdable` (`commands.go`).
2. **Reuse an existing Cmder, or define a new one?** — simple replies (`int`, `string`, `bool`, `[]string`, map) reuse `*IntCmd`, `*StringCmd`, `*BoolCmd`, `*StringSliceCmd`, `*MapStringStringCmd`, … Define a new Cmder only for a structured reply that no existing type fits.
3. **`Foo` vs `FooWithArgs`?** — for commands with optional flags, expose a positional `Foo(...)` for the common path plus `FooWithArgs(ctx, key, *FooArgs)` for the full surface.

## Reference files

| Read this | When |
|-----------|------|
| `references/core-command-pattern.md` | Always — the 7-step Go pattern (interface method, Cmder type, RESP parsing, tests, vet, fmt). Worked example: `LCS`. |
| `references/module-commands.md` | Adding a RediSearch / TimeSeries / VectorSet / Bloom subcommand — naming, RESP2-vs-RESP3 shape differences, where the Cmd type lives. |
| `references/cluster-routing-wiring.md` | Command is keyless, fans out, multi-key, or aggregates across shards. |

When several apply, read in order: core → module → cluster.

## Pitfalls (full list in core-command-pattern.md)

- Forgetting to embed the new `XxxCmdable` interface in `Cmdable` — compiles on `*Client`, silently unreachable via `UniversalClient`.
- Forgetting `Clone()` — pipelines reuse Cmders; shared `val` causes cross-execution bugs.
- Skipping `SetVal` because "nothing calls it" — hooks do, and the `setval` custom-vet check fails the build.
- Using `time.Duration` directly in args — server gets nanoseconds. Convert per spec.

More agent context in redis/go-redis

6 other files this repository gives its agents.