[curquiza]

What

Add meili similar, the one route of POST /indexes/{index_uid}/similar.

Contract

• The command name and flags derive from its routes by the naming rules of docs/contract/commands.md, and each route is reachable by a distinct set of flags, or the exception is recorded with its reason (or this pull request changes the contract and nothing else)
• Output goes through src/lib/output.ts, errors through src/lib/errors.ts
• The command never waits for a human: no prompt, no question, no $EDITOR; a delete command spreads BaseCommand.confirmFlags and its examples carry --yes
• The command never speaks HTTP itself: the SDK or the generated client only, no fetch outside src/lib/clients/

Tests

• --help snapshot added or updated on purpose
• JSON output snapshot for one success case per route and one error case
• Integration test added (Meilisearch API commands only)
• pnpm lint, pnpm typecheck, pnpm test pass locally

Simplicity

• Nothing in the diff exists for a case the API cannot produce, a caller that does not exist, or a generality nobody asked for (rule 16)
• Anything shared lives in src/lib/, is used by this command, and is named below

Docs

• docs/contract/ updated for every name, flag, variable or code this change adds or renames, or nothing to update
• The ADRs that touch this change were read; what they decide still holds, or a new ADR says what changed
• No accepted ADR was edited. A new ADR was added if a decision changed.

Housekeeping

• oclif.manifest.json regenerated
• Changeset added, or the change is invisible to users of the package (docs of this repository, tests, CI)
• New dependency justified below, or none added

Notes for the reviewer

No shared code added, no dependency. The command is 103 lines and reuses connectionFlags, bodyInputFlags, readJsonObjectBody and asNumber. Both exception rows, POST …/similar and its GET twin, already existed in commands.md and api-naming.ts; this pull request only adds the row to the routes table, as #29, #30 and #31 did for theirs.

Three things worth a look:

1. --id is a body field here, not a path parameter. The route takes the index in the path and the document in the body, so --index is required and --id is not: the exception row already says so, and the contract test accepts it because no route of this command carries a path id. --id and --embedder are the two fields SimilarQuery marks required, and neither is required in oclif: a whole body can arrive through --data or --file, and the API names a missing field with its own code, as on multi-search.

2. The response is hits, so --output ndjson is refused, exit 2, like search. The envelope also carries the id it was given, which the integration test pins: --data '{"id":1,…}' --id 3 answers "id": "3", the flag overriding the body field (rule 8).

3. The integration test configures a userProvided embedder and ships the vectors with the three documents, so the suite needs no embedding service and no network: the similarity is the one the fixture wrote. The error case pins the API's own not_found_similar_id for a document that does not exist, exit 1, next to the usual index_not_found, exit 4.

Ran the simplify skill on the diff: reuse, simplification and efficiency found nothing. Altitude raised again what #31 already noted — the rule-8 merge block now lives in three command files (search, update settings, here) and its comment had drifted in my first draft, which I fixed by keeping the sibling's wording byte for byte. A mergeJsonObjectBody in src/lib/input.ts would carry it once, but it touches two commands this pull request does not own, so it still belongs in its own change.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a command to find documents similar to a specified document using a selected embedder.
  • Narrow results with filters and pagination, and control returned attributes, vectors, and ranking details.
  • Provide request options through command-line flags or JSON input from data or a file; flags take precedence when both specify the same option.
  • View the endpoint response directly in the command output.
• Documentation
  • Documented the new command and its API route.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Essentials
• Run ID: c49b3735-20d3-49b5-a0f0-478c37d42fce

Commits

Reviewing files that changed from the base of the PR and between 0adccea and 2c22af3.

Files selected for processing: 1

• src/commands/similar.ts

Files skipped from review as they are similar to previous changes: 1

• src/commands/similar.ts

Limit details: You’ve used all 4 included reviews currently available. Your 34 included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour.

Walkthrough

The CLI adds a similar command for Meilisearch’s similar-documents endpoint. The command accepts request options and JSON body input, sends the request, and outputs the response. Unit and integration tests cover request parameters, results, and API errors.

Changes: Similar Documents Command

Layer / File(s)	Summary
Command surface and registration src/commands/similar.ts, oclif.manifest.json, docs/contract/commands.md, .changeset/first-version.md	The command and manifest register POST /indexes/{index_uid}/similar and define the available flags. The command contract and changelog describe its usage and body input.
Request construction and command tests src/commands/similar.ts, test/helpers/meilisearch-handlers.ts, test/commands/similar.test.ts	The command merges body input with defined flags, with flags taking precedence, calls the endpoint, and outputs its response. Mocked tests cover request parameters, value conversion, output, and errors.
Meilisearch integration coverage test/integration/meilisearch/similar.test.ts	Integration tests create an index with an embedder and documents, then cover similar results, filtering, body and flag overrides, and missing-document and missing-index errors.

Priority: Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  actor Operator
  participant SimilarCommand
  participant searchSimilarDocuments
  participant MeilisearchAPI
  Operator->>SimilarCommand: Run with index and options
  SimilarCommand->>searchSimilarDocuments: Pass request parameters
  searchSimilarDocuments->>MeilisearchAPI: POST /indexes/{index_uid}/similar
  MeilisearchAPI-->>searchSimilarDocuments: Return response
  searchSimilarDocuments-->>SimilarCommand: Return response
  SimilarCommand-->>Operator: Output response

Loading

Possibly related PRs

• meilisearch/cli#25: Implements the related document-search command with a similar search-command contract.
• meilisearch/cli#24: Adds the JSON body validation helper used by meili similar for --data and --file.

Merge Risk: Minimal · up to 2c22a

The similar-documents command is ready to merge after normal checks; no actionable issue was identified.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the main change: adding the meili similar command.
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within survi…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 1 functions across 4 files.

Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}