elastic-cli-usage

# Skill: elastic-cli-usage (verified gotchas) Use `elastic_cli` tool for all CLI operations — credentials are injected automatically. Pass `argv` as a JSON array of strings, e.g. `["es","cluster","health","--json"]`. The `elastic` binary is NOT on PATH in the shell environment; never use bash for this. For anything not listed here, call `elastic_cli` with `["es","<namespace>","--help"]` or `["kb","<namespace>","--help"]`. --- ## Shorthands `es` = `stack es`, `kb` = `stack kb`. Both work. --- ## Prefer MCP/native tools over CLI | Task | Prefer instead | |------|---------------| | ES\|QL queries | `eab_platform_core_execute_esql` | | Index/datastream listing | `eab_platform_core_list_indices` | | Streams | `eab_platform_streams_*` | | Agent builder | `kibana_list_agents`, `kibana_list_tools` | --- ## Gotchas ### Serverless: many cluster APIs return 410 These all fail on serverless with "not available in serverless mode": - `es cluster health` / `stats` / `get-settings` - `es ilm get-lifecycle` / `get-status` Use `es cat count --json` to verify connectivity on serverless instead. ### `es indices list` does not exist Use `es indices get --index "*" --json` or `es indices get-data-stream --json`. ### `es cluster health-report` does not exist The subcommand is `es cluster health`. There is no `health-report`. ### Agent builder subcommands use verbose REST-style names `kb agent-builder agents list` and `tools list` do **not** exist. Real commands: ``` kb agent-builder get-agent-builder-agents --json kb agent-builder get-agent-builder-tools --json ``` Pattern: `<http-method>-<resource-path>` throughout all of `kb`. ### `docs search` and `docs read` require named flags, not positional args ``` # WRONG — "too many arguments" error ["docs","search","index lifecycle management"] ["docs","read","https://www.elastic.co/..."] # CORRECT ["docs","search","--query","index lifecycle management"] ["docs","read","--path","https://www.elastic.co/docs/..."] ``` Also: old `/guide/` URLs return `(no output)`. Use `elastic.co/docs/` URLs. ### `es esql query` requires `--query` flag, not positional ``` # WRONG ["es","esql","query","FROM logs-* | LIMIT 1"] # CORRECT ["es","esql","query","--query","FROM logs-* | LIMIT 1","--json"] ``` ### `kb slo find-slos-op` requires `--space-id` Omitting it returns a validation error. Use `--space-id default`. ### `--output-fields` and `--output-template` are per-subcommand flags (placed at end) They are listed as global flags in the help but must come after the full subcommand. `--output-fields` returns `{}` for array responses — unreliable, avoid it. `--output-template` only works for top-level scalar fields. Just use `--json` and process the output. ### Never block on stdin Never use `--input-file /dev/stdin` or `es helpers watch`. These block forever and hang the `elastic_cli` tool with no way to cancel.