Skip to content

Commit fb730fc

Browse files
theletterfclaudeGPT-5.5cursoragentGPT-5.5
authored
docs: bring CLI docs up to Elastic Docs conventions (#406)
* docs: bring CLI docs up to Elastic Docs conventions Add required frontmatter (type, applies_to, description), fix content type structure for how-to pages (action-verb titles, Before you begin, success checkpoints, Next steps), improve overview stubs, and apply Vale-flagged style fixes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(docs): add missing namespace index pages and regenerate NOTICE.txt docs-builder generates shortcut alias pages (es, elasticsearch, kibana) that link to /cli/stack/es/ and /cli/stack/kb/ but never produces those namespace index pages from the schema. Adding stub pages at those paths resolves the broken-link build error. NOTICE.txt was also out of date; regenerated via generate-notice.mjs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(docs): add stack/es and stack/kb index pages to TOC Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(docs): omit shortcut redirects from cli schema Docs-builder generates broken alias pages from the non-standard shortcuts field, while runtime CLI shortcuts continue to be handled by argv rewriting. Co-authored-by: GPT-5.5 <gpt-5.5@openai.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(docs): clean up CLI reference navigation Move install and configuration pages under the docs landing page and keep stack namespace files as CLI supplemental content only. Co-authored-by: GPT-5.5 <gpt-5.5@openai.com> Co-authored-by: Cursor <cursoragent@cursor.com> * ci: retrigger checks Co-authored-by: GPT-5.5 <gpt-5.5@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com> * docs: override CLI reference title Co-authored-by: GPT-5.5 <gpt-5.5@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(docs): rename stack/es and stack/kb index.md to flat files The docs-builder was generating Sub-namespace links as /cli/stack/es/index instead of /cli/stack/es because the content files were named index.md inside subdirectories. Renaming to flat .md files fixes the broken links. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * ci: retrigger checks * fix(docs): add frontmatter and nav entries for stack/es and stack/kb pages Flat .md files must have a title and be registered in the navigation. Adds frontmatter (description, applies_to, type, navigation_title, H1) and registers both files as children of the CLI schema toc entry. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(docs): use hidden: instead of file: for stack/es and stack/kb fragments Hidden pages are registered in navigation (satisfying the docs-builder requirement) but not shown in the sidebar. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(docs): revert to index.md fragments for stack/es and stack/kb Now that the docs-builder correctly resolves namespace page card URLs (elastic/docs-builder#3489), the supplemental content files can go back to their original subdirectory form (stack/es/index.md). The flat-file approach broke command links on the es/kb pages by displacing the schema-generated page structure. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * ci: retrigger checks * ci: retrigger checks * ci: retrigger checks --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: GPT-5.5 <gpt-5.5@openai.com> Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: GPT-5.5 <gpt-5.5@users.noreply.github.com>
1 parent a8d288d commit fb730fc

12 files changed

Lines changed: 277 additions & 70 deletions

File tree

‎NOTICE.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1133,7 +1133,7 @@ THIS SOFTWARE.
11331133

11341134

11351135
------------------------------------------------------------------------
1136-
yaml@2.8.4
1136+
yaml@2.9.0
11371137
License: ISC
11381138
Repository: https://github.com/eemeli/yaml
11391139
Publisher: Eemeli Aro <eemeli@gmail.com>

‎docs/cli/configuration.md‎

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
1-
# Configuration
1+
---
2+
description: Configure the Elastic CLI by creating a config file with connection contexts for Elasticsearch, Kibana, and Elastic Cloud.
3+
applies_to:
4+
stack: preview
5+
serverless: preview
6+
type: how-to
7+
---
8+
9+
# Configure the Elastic CLI
10+
11+
This guide covers the configuration file format, managing connection contexts with `elastic config`, and using external credential resolvers to keep secrets out of your config file.
12+
13+
## Before you begin
14+
15+
[Install the Elastic CLI](./installation.md) before continuing.
16+
17+
## Set up the config file
218

319
The CLI looks for a config file in your home directory. The following file names are checked in order:
420

@@ -35,7 +51,7 @@ contexts:
3551
3652
Multiple contexts are supported. Override `current_context` for a single command with `--use-context <name>`.
3753

38-
Each context can have any combination of service blocks (`elasticsearch`, `kibana`, `cloud`). Authentication supports `api_key` or `username` + `password`.
54+
Each context can have any combination of service blocks (`elasticsearch`, `kibana`, and `cloud`). Authentication supports `api_key` or `username` + `password`.
3955

4056
## Authoring the config from the CLI
4157

@@ -63,7 +79,17 @@ elastic config context edit local
6379
elastic config context remove old-lab
6480
```
6581

66-
If no OS keychain is available or you pass `--inline-secrets`, the secret is written inline and the file is `chmod 0600`. A warning is emitted when a loaded config has inline secrets at looser-than-0600 permissions.
82+
If no OS keychain is available or you pass `--inline-secrets`, the secret is written inline and the file is `chmod 0600`. The CLI emits a warning when a loaded config has inline secrets at looser-than-0600 permissions.
83+
84+
## Verify your configuration
85+
86+
Run `elastic status` to check connectivity and authentication for all services in the active context:
87+
88+
```bash
89+
elastic status
90+
```
91+
92+
The command reports the result for each configured service (`elasticsearch`, `kibana`, `cloud`). Services not present in the active context are skipped, not treated as failures.
6793

6894
## Credential-safe project creation
6995

@@ -82,14 +108,14 @@ elastic cloud serverless es projects reset-credentials --id <id> \
82108
--save-as scratch --force
83109
```
84110

85-
`--credentials-file <path>` writes a standalone YAML config fragment (0600) at `<path>` instead of mutating the main config. Either flag makes stdout safe to capture into an LLM transcript.
111+
`--credentials-file <path>` writes a standalone YAML config fragment (0600) at `<path>` instead of mutating the main config. Both flags make stdout safe to capture into an LLM transcript.
86112

87113
## External credentials
88114

89115
Any string value in the config file can use `$(resolver:params)` expressions to fetch secrets from external sources at runtime.
90116

91117
:::{warning}
92-
Review config files before using them if you didn't write them yourself. The `$(cmd:...)` and `$(file:...)` resolvers execute programs and read files on your behalf. This applies especially to CI/CD environments where a repo-checked-in config (e.g. via `ELASTIC_CLI_CONFIG_FILE`) can run arbitrary commands on the runner.
118+
Review config files before using them if you didn't write them yourself. The `$(cmd:...)` and `$(file:...)` resolvers run programs and read files on your behalf. This applies especially to CI/CD environments where a repo-checked-in config (for example, via `ELASTIC_CLI_CONFIG_FILE`) can run arbitrary commands on the runner.
93119
:::
94120

95121
`file`
@@ -164,3 +190,9 @@ elasticsearch:
164190
auth:
165191
api_key: $(keychain:elastic-cli/api-key)
166192
```
193+
194+
## Next steps
195+
196+
- Run `elastic --help` to explore available commands.
197+
- Use `elastic cloud serverless` or `elastic cloud hosted` to manage Elastic Cloud resources.
198+
- See the [CLI command reference](./index.md) for the full list of available commands.

‎docs/cli/index.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
1-
Interact with the Elastic Stack and Elastic Cloud from the command line.
1+
---
2+
description: Use the Elastic CLI to interact with the Elastic Stack and Elastic Cloud from the command line.
3+
applies_to:
4+
stack: preview
5+
serverless: preview
6+
type: overview
7+
---
28

3-
Configure the CLI with `elastic config context add` to connect to your Elasticsearch, Kibana, and Elastic Cloud endpoints. See [Installation](./installation.md) and [Configuration](./configuration.md) to get started.
9+
The Elastic CLI (`elastic`) lets you manage Elasticsearch, Kibana, and Elastic Cloud resources from the command line. It supports both self-managed Elastic Stack deployments and Elastic Serverless projects.
10+
11+
Use the CLI to:
12+
- Connect to multiple clusters or projects using named contexts
13+
- Manage Elastic Cloud Hosted deployments and Serverless projects
14+
- Automate operations in CI/CD pipelines and LLM agent workflows
15+
16+
To get started, see [Install the Elastic CLI](./installation.md) and [Configure the Elastic CLI](./configuration.md).

‎docs/cli/installation.md‎

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,39 @@
1-
# Installation
1+
---
2+
description: Install the Elastic CLI globally with npm to run elastic commands from your terminal.
3+
applies_to:
4+
stack: preview
5+
serverless: preview
6+
type: how-to
7+
---
28

3-
Install globally from `npm` so the elastic binary is available on your `PATH`:
9+
# Install the Elastic CLI
410

5-
```bash
6-
npm install -g @elastic/cli
7-
elastic --help
8-
```
11+
## Before you begin
12+
13+
You need Node.js 22 or later and npm (included with Node.js) installed on your system. The CLI is tested on Linux, macOS, and Windows.
14+
15+
## Install globally
16+
17+
1. Install the `elastic` binary to your `PATH`:
18+
19+
```bash
20+
npm install -g @elastic/cli
21+
```
922

10-
If you don't want a global install, you can run a one-off invocation with npx, which downloads and runs the CLI without persisting it:
23+
2. Verify the installation:
24+
25+
```bash
26+
elastic --version
27+
```
28+
29+
## Run without installing
30+
31+
To run a one-off command without a permanent install, use `npx`:
1132

1233
```bash
1334
npx -y @elastic/cli --help
1435
```
36+
37+
## Next steps
38+
39+
- [Configure the Elastic CLI](./configuration.md) to connect to your Elasticsearch, Kibana, or Elastic Cloud endpoints.

‎docs/cli/schema.json‎

Lines changed: 79 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"schemaVersion": 1,
33
"name": "elastic",
4-
"version": "0.1.1",
4+
"version": "0.2.0",
55
"reservedMetaCommands": [
66
"cli-schema"
77
],
@@ -1565,7 +1565,9 @@
15651565
"name": "source",
15661566
"type": "boolean",
15671567
"required": false,
1568-
"summary": "If `false`, turn off source retrieval. You can also specify a comma-separated list of the fields you want to retrieve."
1568+
"summary": "If `false`, turn off source retrieval. You can also specify a comma-separated list of the fields you want to retrieve.",
1569+
"repeatable": true,
1570+
"separator": ","
15691571
},
15701572
{
15711573
"role": "flag",
@@ -2630,7 +2632,9 @@
26302632
"name": "source",
26312633
"type": "boolean",
26322634
"required": false,
2633-
"summary": "The source fields that are returned for matching documents. These fields are returned in the `hits._source` property of the search response. If the `stored_fields` property is specified, the `_source` property defaults to `false`. Otherwise, it defaults to `true`."
2635+
"summary": "The source fields that are returned for matching documents. These fields are returned in the `hits._source` property of the search response. If the `stored_fields` property is specified, the `_source` property defaults to `false`. Otherwise, it defaults to `true`.",
2636+
"repeatable": true,
2637+
"separator": ","
26342638
},
26352639
{
26362640
"role": "flag",
@@ -4646,7 +4650,9 @@
46464650
"name": "source",
46474651
"type": "boolean",
46484652
"required": false,
4649-
"summary": "Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response."
4653+
"summary": "Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.",
4654+
"repeatable": true,
4655+
"separator": ","
46504656
},
46514657
{
46524658
"role": "flag",
@@ -9507,7 +9513,8 @@
95079513
"name": "name",
95089514
"type": "string",
95099515
"required": true,
9510-
"summary": "The view name to remove."
9516+
"summary": "The view name to remove.",
9517+
"repeatable": true
95119518
}
95129519
],
95139520
"summary": "Delete an ES|QL view.",
@@ -10296,7 +10303,9 @@
1029610303
"name": "source",
1029710304
"type": "boolean",
1029810305
"required": false,
10299-
"summary": "Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response."
10306+
"summary": "Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.",
10307+
"repeatable": true,
10308+
"separator": ","
1030010309
},
1030110310
{
1030210311
"role": "flag",
@@ -16714,7 +16723,8 @@
1671416723
"enumValues": [
1671516724
"chat_completion",
1671616725
"completion",
16717-
"text_embedding"
16726+
"text_embedding",
16727+
"embedding"
1671816728
]
1671916729
},
1672016730
{
@@ -18683,7 +18693,9 @@
1868318693
"name": "analyzed-fields",
1868418694
"type": "string",
1868518695
"required": false,
18686-
"summary": "Specify includes and/or excludes patterns to select which fields will be included in the analysis. The patterns specified in excludes are applied last, therefore excludes takes precedence. In other words, if the same field is specified in both includes and excludes, then the field will not be included in the analysis."
18696+
"summary": "Specify includes and/or excludes patterns to select which fields will be included in the analysis. The patterns specified in excludes are applied last, therefore excludes takes precedence. In other words, if the same field is specified in both includes and excludes, then the field will not be included in the analysis.",
18697+
"repeatable": true,
18698+
"separator": ","
1868718699
},
1868818700
{
1868918701
"role": "flag",
@@ -20210,7 +20222,9 @@
2021020222
"name": "analyzed-fields",
2021120223
"type": "string",
2021220224
"required": false,
20213-
"summary": "Specifies `includes` and/or `excludes` patterns to select which fields will be included in the analysis. The patterns specified in `excludes` are applied last, therefore `excludes` takes precedence. In other words, if the same field is specified in both `includes` and `excludes`, then the field will not be included in the analysis. If `analyzed_fields` is not set, only the relevant fields will be included. For example, all the numeric fields for outlier detection. The supported fields vary for each type of analysis. Outlier detection requires numeric or `boolean` data to analyze. The algorithms don’t support missing values therefore fields that have data types other than numeric or boolean are ignored. Documents where included fields contain missing values, null values, or an array are also ignored. Therefore the `dest` index may contain documents that don’t have an outlier score. Regression supports fields that are numeric, `boolean`, `text`, `keyword`, and `ip` data types. It is also tolerant of missing values. Fields that are supported are included in the analysis, other fields are ignored. Documents where included fields contain an array with two or more values are also ignored. Documents in the `dest` index that don’t contain a results field are not included in the regression analysis. Classification supports fields that are numeric, `boolean`, `text`, `keyword`, and `ip` data types. It is also tolerant of missing values. Fields that are supported are included in the analysis, other fields are ignored. Documents where included fields contain an array with two or more values are also ignored. Documents in the `dest` index that don’t contain a results field are not included in the classification analysis. Classification analysis can be improved by mapping ordinal variable values to a single number. For example, in case of age ranges, you can model the values as `0-14 = 0`, `15-24 = 1`, `25-34 = 2`, and so on."
20225+
"summary": "Specifies `includes` and/or `excludes` patterns to select which fields will be included in the analysis. The patterns specified in `excludes` are applied last, therefore `excludes` takes precedence. In other words, if the same field is specified in both `includes` and `excludes`, then the field will not be included in the analysis. If `analyzed_fields` is not set, only the relevant fields will be included. For example, all the numeric fields for outlier detection. The supported fields vary for each type of analysis. Outlier detection requires numeric or `boolean` data to analyze. The algorithms don’t support missing values therefore fields that have data types other than numeric or boolean are ignored. Documents where included fields contain missing values, null values, or an array are also ignored. Therefore the `dest` index may contain documents that don’t have an outlier score. Regression supports fields that are numeric, `boolean`, `text`, `keyword`, and `ip` data types. It is also tolerant of missing values. Fields that are supported are included in the analysis, other fields are ignored. Documents where included fields contain an array with two or more values are also ignored. Documents in the `dest` index that don’t contain a results field are not included in the regression analysis. Classification supports fields that are numeric, `boolean`, `text`, `keyword`, and `ip` data types. It is also tolerant of missing values. Fields that are supported are included in the analysis, other fields are ignored. Documents where included fields contain an array with two or more values are also ignored. Documents in the `dest` index that don’t contain a results field are not included in the classification analysis. Classification analysis can be improved by mapping ordinal variable values to a single number. For example, in case of age ranges, you can model the values as `0-14 = 0`, `15-24 = 1`, `25-34 = 2`, and so on.",
20226+
"repeatable": true,
20227+
"separator": ","
2021420228
},
2021520229
{
2021620230
"role": "flag",
@@ -24365,6 +24379,13 @@
2436524379
"required": false,
2436624380
"summary": "The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles.",
2436724381
"repeatable": true
24382+
},
24383+
{
24384+
"role": "flag",
24385+
"name": "include-implicit",
24386+
"type": "boolean",
24387+
"required": false,
24388+
"summary": "If `true`, include privileges that are implicitly granted by registered `ImplicitPrivilegesProviders` alongside the explicitly configured privileges. Each implicit entry in the response is annotated with `implicitly_granted: true`."
2436824389
}
2436924390
],
2437024391
"summary": "Get roles.",
@@ -50693,6 +50714,34 @@
5069350714
"requiresAuth": true
5069450715
}
5069550716
},
50717+
{
50718+
"path": [
50719+
"cloud",
50720+
"hosted",
50721+
"deployments"
50722+
],
50723+
"name": "get-deployment-es-resource-tiers",
50724+
"parameters": [
50725+
{
50726+
"role": "flag",
50727+
"name": "deployment-id",
50728+
"type": "string",
50729+
"required": true,
50730+
"summary": "Identifier for the Deployment"
50731+
},
50732+
{
50733+
"role": "flag",
50734+
"name": "ref-id",
50735+
"type": "string",
50736+
"required": true,
50737+
"summary": "User-specified RefId for the Resource (or '_main' if there is only one)"
50738+
}
50739+
],
50740+
"summary": "Get Elasticsearch tiers",
50741+
"intent": {
50742+
"requiresAuth": true
50743+
}
50744+
},
5069650745
{
5069750746
"path": [
5069850747
"cloud",
@@ -51036,6 +51085,27 @@
5103651085
"requiresAuth": true
5103751086
}
5103851087
},
51088+
{
51089+
"path": [
51090+
"cloud",
51091+
"hosted",
51092+
"deployments"
51093+
],
51094+
"name": "upgrade-deployment",
51095+
"parameters": [
51096+
{
51097+
"role": "flag",
51098+
"name": "deployment-id",
51099+
"type": "string",
51100+
"required": true,
51101+
"summary": "Identifier for the Deployment"
51102+
}
51103+
],
51104+
"summary": "Upgrade a Deployment to a new Elastic Stack version",
51105+
"intent": {
51106+
"requiresAuth": true
51107+
}
51108+
},
5103951109
{
5104051110
"path": [
5104151111
"cloud",
@@ -53954,35 +54024,5 @@
5395454024
"summary": "Sanitize values for safe use in Elasticsearch"
5395554025
}
5395654026
],
53957-
"shortcuts": [
53958-
{
53959-
"from": "es",
53960-
"to": [
53961-
"stack",
53962-
"es"
53963-
]
53964-
},
53965-
{
53966-
"from": "elasticsearch",
53967-
"to": [
53968-
"stack",
53969-
"es"
53970-
]
53971-
},
53972-
{
53973-
"from": "kb",
53974-
"to": [
53975-
"stack",
53976-
"kb"
53977-
]
53978-
},
53979-
{
53980-
"from": "kibana",
53981-
"to": [
53982-
"stack",
53983-
"kb"
53984-
]
53985-
}
53986-
],
5398754027
"description": "Interface with the Elastic Stack and Elastic Cloud from the command line."
5398854028
}

‎docs/cli/stack/es/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## Description
2+
3+
The `elastic stack es` command group exposes Elasticsearch REST APIs as CLI commands.
4+
5+
These commands are also available using the `elastic es` or `elastic elasticsearch` shortcuts.

‎docs/cli/stack/kb/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## Description
2+
3+
The `elastic stack kb` command group exposes Kibana REST APIs as CLI commands.
4+
5+
These commands are also available using the `elastic kb` or `elastic kibana` shortcuts.

‎docs/docset.yml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,10 @@ dev_docs: true
33

44
toc:
55
- file: index.md
6+
children:
7+
- file: cli/installation.md
8+
- file: cli/configuration.md
69
- cli: cli/schema.json
710
folder: cli
8-
children:
9-
- file: installation.md
10-
- file: configuration.md
11+
title: Elastic CLI command reference
12+
navigation_title: Command reference

‎docs/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
---
2+
description: Use the Elastic CLI to interact with the Elastic Stack and Elastic Cloud from the command line.
3+
applies_to:
4+
stack: preview
5+
serverless: preview
6+
type: overview
7+
---
8+
19
# Elastic CLI
210

311
Interact with the Elastic Stack and Elastic Cloud from the command line.

0 commit comments

Comments
 (0)