{"id":30621904,"url":"https://github.com/fa7ad/esq","last_synced_at":"2026-05-07T13:10:10.776Z","repository":{"id":306263240,"uuid":"1023772888","full_name":"fa7ad/esq","owner":"fa7ad","description":"Elasticsearch Query CLI","archived":false,"fork":false,"pushed_at":"2025-07-24T15:33:33.000Z","size":43,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-24T17:59:11.304Z","etag":null,"topics":["elasticsearch","jq","json","query"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fa7ad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-21T17:08:22.000Z","updated_at":"2025-07-24T15:33:36.000Z","dependencies_parsed_at":"2025-07-24T17:59:19.539Z","dependency_job_id":"673d6937-4562-46da-9df1-633aee41ac44","html_url":"https://github.com/fa7ad/esq","commit_stats":null,"previous_names":["fa7ad/esq"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fa7ad/esq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa7ad%2Fesq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa7ad%2Fesq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa7ad%2Fesq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa7ad%2Fesq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fa7ad","download_url":"https://codeload.github.com/fa7ad/esq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa7ad%2Fesq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272864642,"owners_count":25006040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elasticsearch","jq","json","query"],"created_at":"2025-08-30T15:01:57.908Z","updated_at":"2026-05-07T13:10:05.752Z","avatar_url":"https://github.com/fa7ad.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `esq` - Elasticsearch Query CLI 🕵️‍♂️\n\n**`esq`** is a powerful and simple command-line interface (CLI) for querying your Elasticsearch cluster. It's designed to make searching data easy, whether you prefer KQL, Lucene, or the full Elasticsearch Query DSL. You can also format and process the output on the fly.\n\n## ✨ Features\n\n- **Flexible Querying**: Use the query language you're most comfortable with.\n  - Kibana Query Language (**KQL**) via `--kql`\n  - Lucene query syntax via `--lucene`\n  - Full Elasticsearch Query **DSL** via `--dsl` or from a file with `--query-file`\n- **Time-Range Filtering**: Easily narrow your search to a specific time window using `--from` and `--to`.\n- **Powerful Output Processing**:\n  - Format results as **JSON** or **text**.\n  - Apply **`jq` expressions** directly to the output to reshape the JSON data.\n  - Save results directly to a file.\n- **Flexible Configuration**: Configure `esq` via command-line flags, environment variables (e.g., `ESQ_NODE`), or a YAML config file.\n- **Simple Authentication**: Connect to secure clusters using an **API Key** or **Username/Password**.\n\n---\n\n## 🚀 Installation\n\nYou can install `esq` using `go`:\n\n```sh\ngo install github.com/fa7ad/esq@latest\n```\n\n## ⚙️ Configuration\n\n`esq` can be configured in three ways, with the following order of precedence:\n\n1.  **Command-line flags** (e.g., `--node ...`)\n2.  **Environment variables** (e.g., `export ESQ_NODE=...`)\n3.  **Configuration file**\n\nBy default, `esq` looks for a configuration file at `$HOME/.esq.yaml`. It is also possible to specify a custom config file location using the `--config` flag.\n\n### Example `.esq.yaml`\n\n```yaml\nnode: 'http://localhost:9200'\nindex: 'my-logs-*'\noutput: 'json'\n# api-key: \"your_base64_api_key\"\n# username: \"elastic\"\n# password: \"changeme\"\n```\n\n---\n\n## 💡 Usage\n\nThe only required flags are `--node` and `--index`. You must also provide one query flag: `--kql`, `--lucene`, `--dsl`, or `--query-file`.\n\n### All Flags\n\n```\nA CLI tool to query Elasticsearch.\n\nesq can be configured using command-line flags, environment variables (prefixed with ESQ_),\nor a configuration file (e.g., $HOME/.esq.yaml).\n\nUsage:\n  esq [flags]\n\nFlags:\n  -i, --index string         Elasticsearch index pattern.\n  -n, --node string          Elasticsearch node URL.\n      --api-key string       Elasticsearch API Key for authentication.\n      --username string      Username for basic authentication.\n      --password string      Password for basic authentication.\n      --config string        config file (default is $HOME/.esq.yaml)\n\n  -f, --query-file string    Path to a file containing the Elasticsearch Query DSL (JSON).\n      --dsl string           Elasticsearch Query DSL JSON string.\n      --kql string           Kibana Query Language (KQL) query string.\n      --lucene string        Lucene query string.\n\n      --from string          Start time (ISO8601 or ES-relative like 'now-1d').\n      --to string            End time (ISO8601 or ES-relative like 'now').\n\n  -j, --jq string            Apply a jq expression to the output.\n\n  -s, --size int             Number of results to return. (default 100)\n\n  -o, --output string        Output format (choices: json, text) (default \"text\")\n      --output-file string   Write output to a file instead of stdout.\n\n  -h, --help                 help for esq\n  -v, --version              version for esq\n```\n\n### Examples\n\n**1. Basic KQL Query**\nSearch for successful events for a specific user.\n\n```sh\nesq --node http://localhost:9200 --index 'my-logs-*' --kql \"status:success and user:john\"\n```\n\n**2. DSL Query from a File**\nExecute a complex query stored in a JSON file and format the output as pretty-printed JSON.\n\n```sh\nesq -n https://es.example.com -i orders --query-file my_query.json -o json\n```\n\n**3. Time Range and `jq` Processing**\nFind errors from the last hour and use `jq` to extract just the document ID and source.\n\n```sh\nesq -n http://localhost:9200 -i my-index \\\n  --kql \"log.level:error\" \\\n  --from \"now-1h\" --to \"now\" \\\n  -o json --jq \".hits | map({id: ._id, source: ._source})\"\n```\n\n**4. Authentication**\nAuthenticate using an API key.\n\n```sh\nesq -n https://es.example.com -i metrics \\\n  --kql \"cpu.usage \u003e 90\" \\\n  --api-key \"your_base64_api_key\"\n```\n\nOr use username and password, which can also be set via `ESQ_USERNAME` and `ESQ_PASSWORD` environment variables.\n\n```sh\nesq -n https://secure-es:9200 -i audit-logs \\\n  --username elastic --password changeme \\\n  --kql \"event.action:login_failed\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffa7ad%2Fesq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffa7ad%2Fesq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffa7ad%2Fesq/lists"}