Skip to content

Add the code samples of the Meilisearch documentation - #90

Merged
curquiza merged 2 commits into
mainfrom
code-samples
Nov 9, 2026
Merged

curquiza merged 2 commits into
mainfrom
code-samples

Conversation

@curquiza

@curquiza curquiza commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

What

Add .code-samples.meilisearch.yaml, the meili version of the code samples of the Meilisearch documentation, so the documentation can show a CLI tab before the cURL tab.

The file has 178 samples. Each key is the key of a cURL sample of meilisearch/documentation, and the sample does what that cURL sample does. Each sample first adds the project with meili config set, then runs the command with --project PROJECT_NAME:

meili config set --project PROJECT_NAME --project-url MEILISEARCH_URL --project-api-key API_KEY

meili search --project PROJECT_NAME --index movies --q 'american ninja'

Only the commands that the CLI implements have a sample. Not covered (87 keys): the GET of one setting (settings view returns every setting), CSV and NDJSON documents, experimental routes and fields (chats, dynamic search rules, network, logs, metrics, render template, media, personalize…), routes without a command yet (dumps, snapshots, webhooks, swap, compact, fields, experimental features), samples that need an extra header (X-MS-USER-ID, Accept), and the analytics events of Meilisearch Cloud.

The settings sub-routes become settings update --<setting> <value>, and their reset becomes --<setting> null.

This pull request also:

  • adds rule 19 to CLAUDE.md: a new command adds its samples, and a renamed or removed command or flag updates them, in the same pull request
  • adds the samples to "How to add a command", to the add-command skill and to CONTRIBUTING.md
  • adds a box to the pull request template
  • adds a contract test in test/contract/docs.test.ts: every command and every flag of a sample exists in the manifest

Contract

No command changes in this pull request.

  • The command name and flags derive from its routes by the naming rules of docs/contract/commands.md, or the name the maintainers chose is recorded as an exception with its reason; each route is reachable by a distinct set of flags (or this pull request changes the contract and nothing else): no command added
  • Output goes through src/lib/output.ts, errors through src/lib/errors.ts: no code change
  • The command never waits for a human: no command added
  • The description starts with one short sentence: no command added
  • What the user types sends analytics (rule 18): no command added
  • The command never speaks HTTP itself: no command added

Tests

  • --help snapshot added or updated on purpose: none changed
  • JSON output snapshot for one success case per route and one error case: no command added
  • Integration test added (Meilisearch API commands only): no command added
  • pnpm lint, pnpm typecheck, pnpm test pass locally: lint, typecheck and the unit and contract suites pass (838 tests). The integration suite could not run locally: another Meilisearch with another master key holds localhost:7700 on my machine. Nothing in this change touches it. CI runs it.

Every sample was also run with the built CLI against a local Meilisearch v1.54. None fails with a cli_* error. For each sample, the request that meili --debug sends was compared with the request of the cURL sample: 160 are identical. The other 18 differ on purpose: the CLI uses the POST twin of a GET route (document list, search, similar), document delete --ids sends string ids, and a few samples read a local file or keep a placeholder of the cURL sample.

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: nothing shared added

Docs

  • docs/contract/ updated for every name, flag, variable or code this change adds or renames, or nothing to update: 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.
  • New or changed prose follows the writing style of rule 17 of CLAUDE.md
  • .code-samples.meilisearch.yaml updated by rule 19 of CLAUDE.md

Housekeeping

  • oclif.manifest.json regenerated: no command changed
  • Changeset added by the rules of .changeset/README.md, or the change is invisible to users of the package: the file is not in the npm package
  • New dependency justified below, or none added: none added. The test uses yaml, already a dev dependency

Notes for the reviewer

  • The documentation side comes next: its scripts will fetch this file, show the CLI tab first, and test the samples.
  • Two cURL samples of the documentation are broken, and the meili samples fix them: update_embedders_1 and update_chat_settings_1 put unescaped single quotes in a single-quoted body. joins_delete_orphaned_1 calls POST /indexes/deals/delete-by-filter, which does not exist, so it has no sample here.
  • get_batch_1 uses --id 0: the cURL placeholder BATCH_UID is not an integer, and batch view --id takes one.

Summary by CodeRabbit

  • Documentation
    • Added CLI examples for indexes, documents, search, settings, tasks, keys, batches, statistics, health checks, exports, embeddings, joins, and filters.
    • Expanded contribution guidance to keep examples aligned with command and flag changes.
  • Tests
    • Added checks that examples use available CLI commands and supported flags.

@coderabbitai

coderabbitai Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Explain Change →

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

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: 03be2dbc-42cb-4c0c-acba-e13263dcfc40
Commits

Reviewing files that changed from the base of the PR and between 11cd011 and 3e6da3c.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The pull request adds a Meilisearch CLI documentation sample catalog, contributor guidance for maintaining it, and a contract test that checks sample commands and long flags against the command manifest.

Changes: CLI documentation samples

Layer / File(s) Summary
Define sample requirements
.claude/skills/add-command/SKILL.md, CLAUDE.md, CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md
Contributor instructions and the pull request checklist now cover adding or updating CLI samples for documentation cURL examples and command or flag changes.
Add and validate CLI samples
.code-samples.meilisearch.yaml, test/contract/docs.test.ts
The sample catalog includes CLI examples for Meilisearch commands and search features. The contract test checks that samples use commands in the manifest and long flags declared for those commands.

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

Possibly related PRs

  • meilisearch/cli#70: Defines resource-first command names and flag contracts used by samples in the catalog.
  • meilisearch/cli#42: Defines the project-selection flags used in the sample configuration and commands.
  • meilisearch/cli#21: Defines document commands and flags used by document samples in the catalog.
Merge Risk: Minimal · previous review 11cd0

This PR adds CLI code samples and contributor guidance and does not change CLI behavior. No merge-blocking risk was identified. The CI lint failure comes from generated client drift that this PR does not touch.

Pre-merge checks: Passed 5

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly describes the main change: adding CLI code samples for Meilisearch documentation.
Docstring Coverage Passed No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 1 files. (1 skipped: 1 unsupported.)

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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: a9a63383-c1f4-467b-9db1-5e1a460162ed
Commits

Reviewing files that changed from the base of the PR and between 5cfbafe and 11cd011.

Files selected for processing: 1

  • .code-samples.meilisearch.yaml
Files skipped from review as they are similar to previous changes: 1

  • .code-samples.meilisearch.yaml

Included review availability: This review used your included allowance. 3 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

@curquiza curquiza mentioned this pull request Nov 9, 2026
18 of 19 tasks
Each sample is the meili version of the cURL sample of the same key in
the documentation. Rule 19 of CLAUDE.md and the pull request template ask
to keep them up to date, and a contract test checks that every command
and flag they use exists.
@curquiza
curquiza merged commit e8b60cf into main Nov 9, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant