`es search --input-file` drops top-level `aggs` (and any unrecognised key) without an error

Start by reproducing with the body.json snippet and comparing the CLI result with the direct Elasticsearch call. Then read src/es/request-builder.ts:163-169 and src/lib/json-schema-args.ts:193-206 to see how only schema-declared keys are copied, and check src/lib/ajv-validate.ts for validation behavior. Decide between forwarding and rejecting unknown top-level keys, and handle aggs as an alias of aggregations; done means aggs works and a misspelt key no longer silently returns unfiltered results, with tests for both.

Related to elastic/cli#803

Summary

The ES request builder rebuilds the request body from the keys declared in the command's schema. Any other top-level key in --input-file is dropped before the request is sent. The command exits 0 and prints no warning.

The most common case is aggs. Elasticsearch accepts both aggs and aggregations, and most docs and examples use aggs. The search schema declares only aggregations, so a body written with aggs returns hits and no aggregations key.

A misspelt key fails the same way. Elasticsearch would answer 400 to a misspelt query; the CLI sends the request without it and returns unfiltered results.

Reproduction (v0.7.0, also unchanged on main at fd3359d)

cat > body.json <<'JSON'
{"size":0,"aggs":{"by_day":{"date_histogram":{"field":"@timestamp","calendar_interval":"day"}}}}
JSON

elastic es search --index my-index --input-file body.json | jq 'has("aggregations")'
# false   (exit 0, empty stderr)

curl -s -H "Authorization: ApiKey $KEY" -H 'Content-Type: application/json' \
  "$ES/my-index/_search" -d @body.json | jq 'has("aggregations")'
# true

jq '.aggregations=.aggs | del(.aggs)' body.json | elastic es search --index my-index --input-file - | jq 'has("aggregations")'
# true

Misspelt key:

echo '{"qeury":{"term":{"event.action":"no-such-value"}}}' | elastic es count --index my-index --input-file -
# returns the full index count, exit 0
# Elasticsearch directly: 400 "request does not support [qeury]"

Scope observed

Command	Unknown top-level key
es search	dropped
es count	dropped
es esql query	dropped
es async-search submit	dropped (checked against a local capture server: body keys ["query","size"])
es msearch	bodies inside searches pass through, including aggs
kb …	forwarded (src/kb/request-builder.ts)

Nested keys are not affected: sub-aggregations under aggregations keep aggs.

Mechanism

• src/es/request-builder.ts:163-169 copies only schema-derived arguments (src/lib/json-schema-args.ts:193-206) into a new body. Keys outside the schema never reach it.
• search.request.json in @elastic/schemas 0.10.0 declares properties.aggregations but no aggs.
• AJV does not remove the key (src/lib/ajv-validate.ts sets no removeAdditional), so --no-validate makes no difference.

Conflicts with AGENTS.md

The input rules in AGENTS.md ("Command Authoring Requirements" → "Input") say:

Reject unknown keys: Input with undefined keys MUST produce a validation error naming the unknown field(s). Silent stripping is not acceptable.

For ES commands, an unknown top-level key is neither rejected nor sent. Applied as written, that rule would make aggs a validation error, which still breaks the most common Elasticsearch body shape. Accepting aggs as an alias of aggregations, and rejecting other unknown keys, satisfies both.

Root cause

Two layers, both needed:

1. @elastic/schemas doesn't carry the spec's alias. The specification marks aggregations with @aliases aggs (SearchRequest.ts L414-L419). The JSON Schema output drops it, so aggs reaches the CLI as an unknown key. Reported upstream: elastic/schemas-js#125.
2. The ES request builder drops unknown keys instead of rejecting them (see Mechanism). This is a CLI defect independent of the schemas: a misspelt query returns unfiltered results with exit 0.

If the upstream fix emits aggs as a declared property, the CLI picks it up with no change. If it adds an annotation instead, the CLI must read that annotation. Fixing (2) turns any remaining unknown key into a validation error, as AGENTS.md requires.

Expected

Either option would avoid wrong results with exit 0:

1. Forward unknown top-level body keys, as the Kibana builder does, and let Elasticsearch accept or reject them. At minimum, accept aggs as an alias of aggregations.
2. Or fail (or warn on stderr) when --input-file contains a top-level key the command will not send.

Related

• elastic/cli#170 and elastic/cli#223: rejection of unknown fields, fixed by moving to passthrough schemas. This report is the opposite symptom: no rejection, the key is silently omitted.
• elastic/cli#699: malformed JSON passing validation. It mentions aggs, but not this omission.
• elastic/cli#786: request-routing unification. It keeps service-specific behaviour, so it doesn't appear to change this.