{"id":13783238,"url":"https://github.com/ywangd/peek","last_synced_at":"2025-04-10T05:10:39.709Z","repository":{"id":42216631,"uuid":"281435988","full_name":"ywangd/peek","owner":"ywangd","description":"Peek into Elasticsearch clusters","archived":false,"fork":false,"pushed_at":"2024-01-25T03:56:40.000Z","size":1325,"stargazers_count":17,"open_issues_count":37,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-26T10:04:37.831Z","etag":null,"topics":["cli","elasticsearch","python"],"latest_commit_sha":null,"homepage":"https://peek.readthedocs.io/","language":"Python","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/ywangd.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","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":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-21T15:30:55.000Z","updated_at":"2024-06-25T12:14:09.060Z","dependencies_parsed_at":"2024-06-25T12:14:06.998Z","dependency_job_id":"23266b4b-8b5a-49f4-a0e6-ca896dc05b33","html_url":"https://github.com/ywangd/peek","commit_stats":{"total_commits":221,"total_committers":2,"mean_commits":110.5,"dds":"0.022624434389140302","last_synced_commit":"19ef5bc9958e720c365e7fb7bd7f2f34116fe1c6"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ywangd%2Fpeek","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ywangd%2Fpeek/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ywangd%2Fpeek/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ywangd%2Fpeek/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ywangd","download_url":"https://codeload.github.com/ywangd/peek/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161274,"owners_count":21057555,"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","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":["cli","elasticsearch","python"],"created_at":"2024-08-03T19:00:16.898Z","updated_at":"2025-04-10T05:10:39.688Z","avatar_url":"https://github.com/ywangd.png","language":"Python","funding_links":[],"categories":["Elasticsearch developer tools and utilities"],"sub_categories":["Development and debugging"],"readme":"====\nPeek\n====\n\n.. image:: https://github.com/ywangd/peek/workflows/Peek/badge.svg\n        :target: https://github.com/ywangd/peek\n\nPeek is an interactive CLI tool for working with Elasticsearch clusters.\nIt is like `Kibana Console \u003chttps://www.elastic.co/guide/en/kibana/current/console-kibana.html\u003e`_\nrunning in terminal with additional features for tinkers.\n\n\nInstallation\n------------\n\nPlease note the project requires Python 3.8+. It is recommended to install from PyPI with:\n\n.. code-block:: bash\n\n  pip install es-peek\n\nThe tool is now available as the ``peek`` command. Peek will ask permission to access system keyring\nfor storing credentials.\nThis can be disabled  temporarily by invoking the command as ``peek -e use_keyring=False``\nor permanently by setting ``use_keyring = False`` in `peekrc \u003cpeek/peekrc\u003e`_ file\n\nBesides HTTP calls to Elasticsearch clusters, type ``help`` to see a list of builtin functions.\nTo **enable auto-completions** for APIs, run the ``_download_api_specs`` builtin function\n(note the leading underscore) to download API spec file from the\n`Elasticsearch Specification project \u003chttps://github.com/elastic/elasticsearch-specification\u003e`_.\n\nAlternatively, peek can also be installed from source with:\n\n.. code-block:: bash\n\n    python setup.py install\n\nFeatures\n--------\n\nPeek supports most editing features offered by\n`Kibana Console \u003chttps://www.elastic.co/guide/en/kibana/current/console-kibana.html\u003e`_,\ne.g. auto-completion, syntax highlighting, auto-formatting, auto-indent,\npar-editing, triple-quotes, etc. It also offers following additional features:\n\n* Lightweight CLI tool\n* Multiplex a single terminal session to multiple Elasticsearch clusters or multiple connections to a single cluster\n* Flexible usages of quotes, comma, comments for the JSON payload, case-insensitive http method names\n* Multiple authentication schemes, including UserPass, API key, Token, SAML, OIDC, Kerberos, PKI\n* Support run-as, x-opaque-id and arbitrary request headers\n* Load JSON payload from external files\n* Run file input in batch mode\n* Readline editing features, e.g. ``Ctrl-_`` for undo, ``Ctrl-r`` for reverse search, etc.\n* History management\n* Capture terminal input and output into file\n* Connect to `Elastic Cloud \u003chttps://cloud.elastic.co/\u003e`_ with Cloud ID\n* Shell out for system commands\n* Minimal scripting support\n* Extensible via external scripts\n\nSample Usages\n-------------\n\nAssuming a locally running Elasticsearch cluster, start a Peek session with:\n\n.. code-block:: bash\n\n  peek --hosts localhost:9200 --username elastic\n\nThe following sample is a quick guide on Peek usages:\n\n.. code-block:: javascript\n\n  // Download the API schema from the elasticsearch-specification project to enable auto-completion\n  // If the output says the schema file already exists, you can safely proceed to the next command.\n  _download_api_specs\n\n  // NOTE a blank line is needed to trigger API execution, or type \"ESC + Enter\" to execute regardlessly\n  // Exit the interactive session any time by pressing Ctrl-d or type exit\n  GET /_cluster/health  // comment is allowed almost anywhere\n\n  // Index a single document\n  POST /my-index/_doc\n  {'foo': \"bar\"}  // both single and double quotes are acceptable\n\n  // Bulk indexing\n  // Press \u003cF3\u003e to switch between pretty and compact formatting for the JSON payload\n  PUT _bulk\n  {\"index\":{\"_index\":\"test\",\"_id\":\"1\"}}\n  {\"value\":\"1\",\"category\":\"click\"}\n  {\"index\":{\"_index\":\"test\",\"_id\":\"2\"}}\n  {\"value\":\"2\",\"category\":\"click\"}\n\n  // Auto encoding for date math expression\n  // The following is encoded automatically into \"PUT /%3Cmy-index-%7Bnow%2Fd%7D%3E\" on the background\n  PUT /\u003cmy-index-{now/d}\u003e\n\n  // Shell out to download the EQL threat hunting demo file\n  !curl -o normalized-T1117-AtomicRed-regsvr32.json https://raw.githubusercontent.com/elastic/elasticsearch/master/docs/src/test/resources/normalized-T1117-AtomicRed-regsvr32.json\n\n  // Bulk indexing the above downloaded file\n  POST my-index-000001/_bulk\n  @normalized-T1117-AtomicRed-regsvr32.json\n\n  // Execute an EQL query (triple quotes can be either ''' or \"\"\")\n  GET /my-index-000001/_eql/search?filter_path=-hits.events\n  {\n    \"query\": \"\"\"\n      any where process.name == \"regsvr32.exe\"\n    \"\"\",\n    \"size\": 200\n  }\n\n  // Create an API key\n  PUT _security/api_key\n  {\n    \"name\": \"key-1\",  // extra comma is OK, and this comment is ok as well\n  }\n\n  // Connect using the above generated API key\n  // The dot notation is used to index into JSON object and array\n  connect api_key=_.'id' + \":\" + _.'api_key' hosts='localhost:9200'  // Quotes are necessary for strings\n\n  // Connect to Elastic Cloud with Cloud ID\n  connect cloud_id='YOUR_CLOUD_ID' username='elastic'\n\n  // Issue a call to the cloud cluster\n  get /  // HTTP method is case-insensitive\n  get / conn=0  // send the request to the first connection (zero-based index) with the conn option\n\n  // Check configuration location and values\n  config\n\n  // List available connections\n  connection\n  connection @info  // check details\n  connection rename='my-cloud-cluster'  // give a friendly name to the current connection\n  connection 0  // switch to the first connection\n  connection remove=0  // remove the first connection\n  connection 'my-cloud-cluster'  // switch to the cloud cluster connection\n\n  // Save the connections we have so far. Session is also auto-saved on exit.\n  session @save  // it can be loaded later with \"session @load\"\n\n  // Session auto-load on start up can be enabled by set \"auto_load_session = True\" in peekrc file.\n  // This helps preserving connections across restart.\n\n  // Builtin help\n  help  // list available functions\n  help session  // a bit more detailed info about the \"session\" builtin function\n\n  // Capture the terminal I/O\n  capture @start\n  capture  // show capture status\n\n  // Run-AS and other headers\n  GET _security/_authenticate runas='foo' xoid='my-x-opaque-id' headers={'some-other-header': 'blah'}\n\n  // Show only the first role from previous response\n  echo _.\"roles\".0\n\n  // If the cluster has SAML integration configured, authenticate with saml\n  // Note this opens a web browser to perform the front-channel flow\n  saml_authenticate\n\n  // Load and run an external script\n  run 'my-setup.es'\n\n  // Stop the capture\n  capture @stop\n\n  // Minimal scripting for populating an index\n  let tags = range(0, 100)\n  for i in tags {\n    PUT (\"my-index/_doc/\" + i)\n    { 'tag': i, \"value\": i * i }\n  }\n\n  // Or with bulk index\n  for i in range(1, 100) {  // first prepare the payload file\n    echo {\"index\":{\"_index\":\"test\",\"_id\":\"\" + i}} file='payload.json'\n    echo {\"value\":i,\"category\":\"click\"} file='payload.json'\n  }\n  // Now bulk indexing with the above generated file\n  PUT _bulk\n  @payload.json\n\nThe tool can also run in batch mode. Assuming above commands are saved in a file called ``script.es``,\nit can be executed as:\n\n.. code-block:: bash\n\n  # Positional argument\n  peek script.es\n\n  # Pipe\n  cat script.es | peek\n\n  # Or with heredoc\n  peek \u003c\u003c EOF\n  GET /_cluster/health\n  // etc\n  EOF\n\nExternal scripts can used to provide extra functions. They are simple Python scripts that define\nand expose callabes under a variable named ``EXPORTS``. Please refer `natives.py \u003cpeek/natives.py\u003e`_\nfor examples.\n\nPlease also read `Usages \u003cdocs/usage.rst\u003e`_ for more details.\n\nCredits\n-------\n`Pgcli \u003chttps://github.com/dbcli/pgcli\u003e`_ has been a great reference of learning how to use\n`prompt-toolkit \u003chttps://github.com/prompt-toolkit/python-prompt-toolkit\u003e`_, which is a critical\ndependency of this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fywangd%2Fpeek","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fywangd%2Fpeek","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fywangd%2Fpeek/lists"}