|
| 1 | +# Configuration |
| 2 | + |
| 3 | +The CLI looks for a config file in your home directory. The following file names are checked in order: |
| 4 | + |
| 5 | +1. `.elasticrc` |
| 6 | +2. `.elasticrc.json` |
| 7 | +3. `.elasticrc.yaml` |
| 8 | +4. `.elasticrc.yml` |
| 9 | + |
| 10 | +Place your config at `~/.elasticrc.yml` (recommended). To use a file in a different location, pass `--config-file <path>` or set `ELASTIC_CLI_CONFIG_FILE`. The flag takes precedence over the environment variable. |
| 11 | + |
| 12 | +```yaml |
| 13 | +current_context: local |
| 14 | + |
| 15 | +contexts: |
| 16 | + local: |
| 17 | + elasticsearch: |
| 18 | + url: http://localhost:9200 |
| 19 | + auth: |
| 20 | + api_key: your-api-key-here |
| 21 | + kibana: |
| 22 | + url: http://localhost:5601 |
| 23 | + auth: |
| 24 | + api_key: your-api-key-here |
| 25 | + staging: |
| 26 | + elasticsearch: |
| 27 | + url: https://my-cluster.es.us-east-1.aws.elastic.cloud |
| 28 | + auth: |
| 29 | + api_key: your-api-key-here |
| 30 | + cloud: |
| 31 | + url: https://api.elastic-cloud.com |
| 32 | + auth: |
| 33 | + api_key: your-cloud-api-key-here |
| 34 | +``` |
| 35 | +
|
| 36 | +Multiple contexts are supported. Override `current_context` for a single command with `--use-context <name>`. |
| 37 | + |
| 38 | +Each context can have any combination of service blocks (`elasticsearch`, `kibana`, `cloud`). Authentication supports `api_key` or `username` + `password`. |
| 39 | + |
| 40 | +## Authoring the config from the CLI |
| 41 | + |
| 42 | +Instead of hand-editing YAML, the `elastic config` command group creates and maintains contexts and stores secrets in the OS keychain when available (macOS Keychain, Linux libsecret, `pass`, Windows Credential Manager). The YAML then holds a resolver expression like `$(keychain:...)` rather than the raw secret. |
| 43 | + |
| 44 | +```bash |
| 45 | +# Add a new context (API key goes to the keychain) |
| 46 | +elastic config context add local \ |
| 47 | + --es-url http://localhost:9200 \ |
| 48 | + --es-api-key your-api-key |
| 49 | +
|
| 50 | +# List contexts |
| 51 | +elastic config context list |
| 52 | +
|
| 53 | +# Switch the active context |
| 54 | +elastic config current-context set staging |
| 55 | +
|
| 56 | +# Patch an existing context |
| 57 | +elastic config context edit local --es-url http://localhost:9201 |
| 58 | +
|
| 59 | +# Open the context as YAML in $EDITOR |
| 60 | +elastic config context edit local |
| 61 | +
|
| 62 | +# Remove a context (keychain entries are cleaned up) |
| 63 | +elastic config context remove old-lab |
| 64 | +``` |
| 65 | + |
| 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. |
| 67 | + |
| 68 | +## Credential-safe project creation |
| 69 | + |
| 70 | +For agent and LLM workflows, `serverless projects create` and `reset-credentials` accept `--save-as <context>` to avoid leaking admin credentials through stdout: |
| 71 | + |
| 72 | +```bash |
| 73 | +elastic cloud serverless es projects create --wait --save-as scratch \ |
| 74 | + --name scratch-es --region-id aws-us-east-1 |
| 75 | +
|
| 76 | +# stdout has endpoints + a `savedAs: scratch` marker, password is redacted. |
| 77 | +# The keychain now holds scratch:elasticsearch.auth.password etc. |
| 78 | +elastic --use-context scratch stack es indices list |
| 79 | + |
| 80 | +# Rotate credentials; URL stays, only the password moves. |
| 81 | +elastic cloud serverless es projects reset-credentials --id <id> \ |
| 82 | + --save-as scratch --force |
| 83 | +``` |
| 84 | + |
| 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. |
| 86 | + |
| 87 | +## External credentials |
| 88 | + |
| 89 | +Any string value in the config file can use `$(resolver:params)` expressions to fetch secrets from external sources at runtime. |
| 90 | + |
| 91 | +:::{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. |
| 93 | +::: |
| 94 | + |
| 95 | +`file` |
| 96 | +: Reads the contents of a file (trimmed). Useful for Docker/Kubernetes secrets mounted at `/run/secrets/`. |
| 97 | + |
| 98 | + ```yaml |
| 99 | + auth: |
| 100 | + api_key: $(file:/run/secrets/elastic_api_key) |
| 101 | + ``` |
| 102 | + |
| 103 | +`env` |
| 104 | +: Reads an environment variable. |
| 105 | + |
| 106 | + ```yaml |
| 107 | + auth: |
| 108 | + api_key: $(env:ELASTIC_API_KEY) |
| 109 | + ``` |
| 110 | + |
| 111 | +`cmd` |
| 112 | +: Executes a shell command and uses its stdout (trimmed) as the value. |
| 113 | + |
| 114 | + ```yaml |
| 115 | + auth: |
| 116 | + api_key: $(cmd:pass show elastic/api-key) |
| 117 | + ``` |
| 118 | + |
| 119 | +`keychain` *(macOS only)* |
| 120 | +: Reads a password from the macOS Keychain using `service/account` format. |
| 121 | + |
| 122 | + ```yaml |
| 123 | + auth: |
| 124 | + api_key: $(keychain:elastic-cli/api-key) |
| 125 | + ``` |
| 126 | + |
| 127 | + To store a value: `security add-generic-password -s elastic-cli -a api-key -w` |
| 128 | + |
| 129 | +`secret_service` *(Linux only)* |
| 130 | +: Reads a secret from GNOME Keyring or KWallet via `secret-tool`. |
| 131 | + |
| 132 | + ```yaml |
| 133 | + auth: |
| 134 | + api_key: $(secret_service:elastic-cli/api-key) |
| 135 | + ``` |
| 136 | + |
| 137 | + To store a value: `secret-tool store --label='Elastic API Key' service elastic-cli account api-key` |
| 138 | + |
| 139 | +`pass` *(cross-platform)* |
| 140 | +: Reads the first line from `pass show`. Works on Linux, macOS, and Windows (WSL). |
| 141 | + |
| 142 | + ```yaml |
| 143 | + auth: |
| 144 | + api_key: $(pass:elastic/api-key) |
| 145 | + ``` |
| 146 | + |
| 147 | + To store a value: `pass insert elastic/api-key` |
| 148 | + |
| 149 | +`credential_manager` *(Windows only)* |
| 150 | +: Reads a credential from Windows Credential Manager. Requires the `CredentialManager` PowerShell module. |
| 151 | + |
| 152 | + ```yaml |
| 153 | + auth: |
| 154 | + api_key: $(credential_manager:elastic-cli/api-key) |
| 155 | + ``` |
| 156 | + |
| 157 | + To store a value: `New-StoredCredential -Target elastic-cli/api-key -UserName _ -Password <key>` |
| 158 | + |
| 159 | +Expressions can appear in any string field, including URLs: |
| 160 | + |
| 161 | +```yaml |
| 162 | +elasticsearch: |
| 163 | + url: https://$(env:ES_HOST):9200 |
| 164 | + auth: |
| 165 | + api_key: $(keychain:elastic-cli/api-key) |
| 166 | +``` |
0 commit comments