--- title: Configure the Elastic CLI description: Configure the Elastic CLI by creating a config file with connection contexts for Elasticsearch, Kibana, and Elastic Cloud. url: https://www.elastic.co/elastic/docs-builder/docs/4097/reference/elastic-cli/cli/configuration applies_to: - Elastic Cloud Serverless: Preview - Elastic Stack: Preview --- # Configure the Elastic CLI This guide covers the configuration file format, managing connection contexts with `elastic config`, and using external credential resolvers to keep secrets out of your configuration file. ## Before you begin [Install the Elastic CLI](https://www.elastic.co/elastic/docs-builder/docs/4097/reference/elastic-cli/cli/installation) before continuing. ## Configure contexts The CLI organizes connection settings into named contexts. Each context can contain connection and authentication details for one Elasticsearch endpoint, one Kibana endpoint, and one Elastic Cloud endpoint. One context can be set as the current context. The CLI uses it when a command doesn't specify another context with `--use-context `. Contexts are stored in the CLI configuration file. You can edit this file directly or use `elastic config` to update it. ### Edit the configuration file The CLI looks for a config file in your home directory. The following file names are checked in order: 1. `.elasticrc` 2. `.elasticrc.json` 3. `.elasticrc.yaml` 4. `.elasticrc.yml` Place your config at `~/.elasticrc.yml` (recommended). To use a file in a different location, pass `--config-file ` or set the `ELASTIC_CLI_CONFIG_FILE` environment variable. The flag takes precedence over the environment variable. ```yaml current_context: local contexts: local: elasticsearch: url: http://localhost:9200 auth: api_key: your-api-key-here kibana: url: http://localhost:5601 auth: api_key: your-api-key-here staging: elasticsearch: url: https://my-cluster.es.us-east-1.aws.elastic.cloud auth: api_key: your-api-key-here cloud: url: https://api.elastic-cloud.com auth: api_key: your-cloud-api-key-here ``` A context can contain any combination of the `elasticsearch`, `kibana`, and `cloud` service blocks. Each block specifies an endpoint URL and optional authentication details. Elasticsearch and Kibana support API key or username and password authentication; Elastic Cloud requires an API key. Elastic provides different API key types for different APIs. The Elastic CLI supports: - [Elasticsearch API keys](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4097/deploy-manage/api-keys/elasticsearch-api-keys) for accessing Elasticsearch and Kibana APIs in self-managed or Elastic Cloud on Kubernetes clusters and Elastic Cloud Enterprise or Elastic Cloud Hosted deployments. - [Serverless project API keys](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4097/deploy-manage/api-keys/serverless-project-api-keys) for accessing Elasticsearch and Kibana APIs within a specific Elastic Cloud Serverless project. - [Elastic Cloud API keys](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4097/deploy-manage/api-keys/elastic-cloud-api-keys) for managing organizations, Elastic Cloud Hosted deployments, and Elastic Cloud Serverless projects. In Serverless, a Cloud API key with **Cloud, Elasticsearch, and Kibana API** access and an appropriate role for each relevant project can also call project-level Elasticsearch and Kibana APIs. Elastic Cloud API keys can't authenticate against Elasticsearch or Kibana endpoints on Elastic Cloud Hosted. Refer to [Elastic API keys](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4097/deploy-manage/api-keys) to compare all available key types. Refer to the [CLI configuration reference](https://www.elastic.co/elastic/docs-builder/docs/4097/reference/elastic-cli/cli/configuration_reference) for all available config options. ### Use `elastic config` The `elastic config` command group creates and maintains contexts and stores secrets in the operating system's credential store when available (macOS Keychain, Linux libsecret, `pass`, Windows Credential Manager). In that case, the configuration file contains a resolver expression such as `$(keychain:...)` instead of the secret value. ```bash # Add a new context (API key goes to the keychain) elastic config context add local \ --es-url http://localhost:9200 \ --es-api-key your-api-key # List contexts elastic config context list # Switch the active context elastic config current-context set staging # Patch an existing context elastic config context edit local --es-url http://localhost:9201 # Open the context as YAML in $EDITOR elastic config context edit local # Remove a context (keychain entries are cleaned up) elastic config context remove old-lab ``` If no operating system credential store is available or you pass `--inline-secrets`, the CLI writes secrets directly to the configuration file and restricts access to the current user (file mode `0600` on Linux and macOS). It warns you if a configuration file containing inline secrets has broader permissions. ## Verify your configuration Run `elastic status` to check connectivity and authentication for the services configured in the current context: ```bash elastic status ``` To check another context without making it the current context, pass `--use-context`: ```bash elastic --use-context staging status ``` The command reports a result for each configured service (`elasticsearch`, `kibana`, or `cloud`) in the selected context. ## Credential-safe project creation - Elastic Cloud Serverless: Preview When you create a Serverless project, the Elastic Cloud API returns default administrator credentials for immediate access. The CLI redacts the password by default. You can access the project with either these credentials or an [API key](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4097/deploy-manage/api-keys). For ongoing access, we recommend using an API key with only the permissions required for your use case. The CLI provides the following options for handling the default credentials: - `--save-as ` stores the project's endpoints and credentials in a named context. The CLI uses the operating system's credential store when available. - `--credentials-file ` writes a standalone YAML configuration file with file mode `0600` without modifying the main configuration file. - `--show-credentials` prints the credentials to standard output in plain text. Avoid this option unless you need to capture the password manually. `--save-as` and `--credentials-file` retain the credentials while keeping the password redacted in standard output, making command output safe to capture in agent and LLM workflows. For example, create a project and store its endpoints and credentials in a context named `scratch`: ```bash elastic cloud serverless projects search create \ --name scratch-es \ --region-id aws-us-east-1 \ --wait \ --save-as scratch ``` You can then use the context to access the project: ```bash elastic --use-context scratch es info ``` To create a separate configuration file instead, use `--credentials-file`: ```bash elastic cloud serverless projects search create \ --name scratch-es \ --region-id aws-us-east-1 \ --wait \ --credentials-file ./scratch.yml ``` You can then use the file as a standalone CLI configuration: ```bash elastic --config-file ./scratch.yml es info ``` To rotate the default credentials and update an existing context, run: ```bash elastic cloud serverless projects search reset-credentials \ --id \ --save-as scratch \ --force ``` ## External credentials Any string value in the config file can use `$(resolver:params)` expressions to fetch secrets from external sources at runtime. 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. Reads the contents of a file (trimmed). Useful for Docker/Kubernetes secrets mounted at `/run/secrets/`. ```yaml auth: api_key: $(file:/run/secrets/elastic_api_key) ``` Reads an environment variable. ```yaml auth: api_key: $(env:ELASTIC_API_KEY) ``` Executes a shell command and uses its stdout (trimmed) as the value. ```yaml auth: api_key: $(cmd:pass show elastic/api-key) ``` Reads a password from the macOS Keychain using `service/account` format. ```yaml auth: api_key: $(keychain:elastic-cli/api-key) ``` To store a value: `security add-generic-password -s elastic-cli -a api-key -w` Reads a secret from GNOME Keyring or KWallet via `secret-tool`. ```yaml auth: api_key: $(secret_service:elastic-cli/api-key) ``` To store a value: `secret-tool store --label='Elastic API Key' service elastic-cli account api-key` Reads the first line from `pass show`. Works on Linux, macOS, and Windows (WSL). ```yaml auth: api_key: $(pass:elastic/api-key) ``` To store a value: `pass insert elastic/api-key` Reads a credential from Windows Credential Manager. Requires the `CredentialManager` PowerShell module. ```yaml auth: api_key: $(credential_manager:elastic-cli/api-key) ``` To store a value: `New-StoredCredential -Target elastic-cli/api-key -UserName _ -Password ` Expressions can appear in any string field, including URLs: ```yaml elasticsearch: url: https://$(env:ES_HOST):9200 auth: api_key: $(keychain:elastic-cli/api-key) ``` ## Next steps - Run `elastic --help` to explore available commands. - Refer to the [CLI command reference](https://www.elastic.co/elastic/docs-builder/docs/4097/reference/elastic-cli/cli) for the full list of available commands. - Follow [Connect to Elastic Cloud with the Elastic CLI](https://www.elastic.co/elastic/docs-builder/docs/4097/reference/elastic-cli/cli/manage-elastic-cloud) to configure a connection and run example operations against the Elastic Cloud API.