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.

Install the Elastic CLI before continuing.

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 <name>.

Contexts are stored in the CLI configuration file. You can edit this file directly or use elastic config to update it.

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 <path> or set the ELASTIC_CLI_CONFIG_FILE environment variable. The flag takes precedence over the environment variable.

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
		

1. Sets local as the context used when --use-context is not specified.

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.

Refer to the CLI configuration reference for all available config options.

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.

# 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.

Run elastic status to check connectivity and authentication for the services configured in the current context:

elastic status
		

To check another context without making it the current context, pass --use-context:

elastic --use-context staging status
		

The command reports a result for each configured service (elasticsearch, kibana, or cloud) in the selected context.

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. 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 <context> stores the project's endpoints and credentials in a named context. The CLI uses the operating system's credential store when available.
• --credentials-file <path> 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.

For example, create a project and store its endpoints and credentials in a context named scratch:

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:

elastic --use-context scratch es info
		

To create a separate configuration file instead, use --credentials-file:

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:

elastic --config-file ./scratch.yml es info
		

To rotate the default credentials and update an existing context, run:

elastic cloud serverless projects search reset-credentials \
  --id <project-id> \
  --save-as scratch \
  --force
		

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

file

Reads the contents of a file (trimmed). Useful for Docker/Kubernetes secrets mounted at /run/secrets/.

auth:
  api_key: $(file:/run/secrets/elastic_api_key)
		

env

Reads an environment variable.

auth:
  api_key: $(env:ELASTIC_API_KEY)
		

cmd

Executes a shell command and uses its stdout (trimmed) as the value.

auth:
  api_key: $(cmd:pass show elastic/api-key)
		

keychain (macOS only)

Reads a password from the macOS Keychain using service/account format.

auth:
  api_key: $(keychain:elastic-cli/api-key)
		

To store a value: security add-generic-password -s elastic-cli -a api-key -w

secret_service (Linux only)

Reads a secret from GNOME Keyring or KWallet via secret-tool.

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

pass (cross-platform)

Reads the first line from pass show. Works on Linux, macOS, and Windows (WSL).

auth:
  api_key: $(pass:elastic/api-key)
		

To store a value: pass insert elastic/api-key

credential_manager (Windows only)

Reads a credential from Windows Credential Manager. Requires the CredentialManager PowerShell module.

auth:
  api_key: $(credential_manager:elastic-cli/api-key)
		

To store a value: New-StoredCredential -Target elastic-cli/api-key -UserName _ -Password <key>

Expressions can appear in any string field, including URLs:

elasticsearch:
  url: https://$(env:ES_HOST):9200
  auth:
    api_key: $(keychain:elastic-cli/api-key)
		

• Run elastic --help to explore available commands.
• Refer to the CLI command reference for the full list of available commands.
• Follow Connect to Elastic Cloud with the Elastic CLI to configure a connection and run example operations against the Elastic Cloud API.