Configuration file reference

The .elasticrc configuration file defines connection contexts, credentials, command policies, and CLI behavior. See Configure the Elastic CLI to learn where to store the file and how to resolve secret values.

Supported properties

Name	Type	Required	Default value	Description
`current_context`	string	yes	-	The key of the context (from `contexts`) that is active by default. Must reference an existing key in `contexts`.
`contexts`	object	yes	-	A map of named contexts, each a collection of service blocks (`elasticsearch`, `kibana`, `cloud`) and an optional per-context `commands` policy. At least one map entry is required, and each context must define at least one service block. See contexts.
`commands`	object	no	-	The root-level command allow/deny policy. Overridden by a context's own `commands` policy when present. See command policy.
`default_profile`	string (`serverless` \| `stack` \| `default`)	no	-	Fallback built-in profile applied to any context that does not set its own `commands.profile`. Overridden by a per-context `commands.profile` and by the `--command-profile` CLI flag.
`banner`	boolean	no	`true`	Whether to show the startup banner.
`telemetry`	boolean	no	`true`	Whether to collect anonymous usage telemetry. Set to `false` to turn off collection of anonymous telemetry. Overridden by the `ELASTIC_CLI_TELEMETRY` environment variable.
`detect_version`	boolean	no	`true`	Whether to auto-detect the Elasticsearch and Kibana `version` of each context. Set to `false` to never detect. See Service block.

`contexts.<name>`

Each entry in contexts is a named context: a collection of optional service blocks plus an optional command policy. At least one of elasticsearch, kibana, or cloud is required.

Name	Type	Required	Default value	Description
`elasticsearch`	object	no¹	-	Elasticsearch service block. See Service block.
`kibana`	object	no¹	-	Kibana service block. See Service block.
`cloud`	object	no¹	-	Elastic Cloud service block. See Service block.
`commands`	object	no	-	Per-context command allow/deny policy. Takes precedence over the root-level `commands` policy.

¹ At least one of elasticsearch, kibana, or cloud must be present.

Service block (`elasticsearch`, `kibana`, `cloud`)

The endpoint URL and authentication credentials for a single service.

Name	Type	Required	Default value	Description
`url`	string	yes	-	Service endpoint URL. Must be a valid URL using the `http://` or `https://` scheme.
`auth`	object	no	-	Authentication credentials for the service. Elasticsearch and Kibana support API key or basic authentication; Elastic Cloud requires an API key.
`version`	string or object	no	-	Target version hint for command availability filtering. Accepts a version string (examples: `9.2`, `9.2.3`) or the literal `serverless`. When absent, the CLI detects the version before running the next command and stores it in `{ value: string, checked_ts: string }` format. Auto-detection will not run again until the datetime string stored in `checked_ts` is more than 30 days in the past. If detection fails, the CLI stores only `{ checked_ts: string }` (or, when a `value` already exists, keeps it and updates `checked_ts`). A `version` with a `checked_ts` but no `value` is retried after 1 hour. Detection runs only for `elastic stack` subcommands, never for `--help` or `--dry-run`. Auto-detection will not run when `version: string` format is used, so you will need to manually update the value when your cluster is upgraded. Setting the top-level `detect_version` to `false` turns off auto-detection. See Supported versions and version filtering.

Auth: API key

Name	Type	Required	Default value	Description
`api_key`	string	yes	-	API key authentication credential.

Auth: Basic

Name	Type	Required	Default value	Description
`username`	string	yes	-	Basic auth username.
`password`	string	yes	-	Basic auth password.

Command policy (`commands`)

Policy controlling which commands are permitted to run. Applies at the root level and, optionally, per-context.

Name	Type	Required	Default value	Description
`profile`	string (`serverless` \| `stack` \| `default`)	no	-	Built-in allow-list profile. Mutually exclusive with `allowed`.
`allowed`	array of strings	no	-	Explicit allow-list of command names/namespaces. Entries can use a trailing wildcard (example: `stack.es.*`) to match a namespace. Mutually exclusive with `profile` and `blocked`.
`blocked`	array of strings	no	-	Explicit deny-list of command names/namespaces (everything else is allowed). Entries can use a trailing wildcard. Mutually exclusive with `allowed`.

Valid combinations:

profile alone; use a built-in allow-list.
profile + blocked; built-in allow-list with additional restrictions.
allowed alone; explicit allow-list.
blocked alone; explicit deny-list.

Built-in profiles (profile / default_profile):

Profile	Description
`serverless`	Only commands that work on Elastic Cloud Serverless. Hides `cloud hosted` and exposes `cloud serverless` plus the majority of stack commands.
`stack`	Full command surface, including self-managed / hosted-only APIs. Equivalent to having no policy (allow everything).
`default`	Alias for `serverless`; the most conservative baseline, recommended for agents and LLM-based tooling.