{"id":28656053,"url":"https://github.com/dhth/ecscope","last_synced_at":"2025-08-23T04:14:51.486Z","repository":{"id":280490826,"uuid":"942168291","full_name":"dhth/ecscope","owner":"dhth","description":"monitor AWS ECS resources from the terminal","archived":false,"fork":false,"pushed_at":"2025-06-12T22:06:31.000Z","size":403,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-12T22:56:04.219Z","etag":null,"topics":["aws","aws-ecs","ecs","ecs-service","ecs-task","ratatui"],"latest_commit_sha":null,"homepage":"https://tools.dhruvs.space/ecscope","language":"Rust","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/dhth.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-03-03T17:22:58.000Z","updated_at":"2025-06-12T22:06:34.000Z","dependencies_parsed_at":"2025-05-26T09:35:54.051Z","dependency_job_id":null,"html_url":"https://github.com/dhth/ecscope","commit_stats":null,"previous_names":["dhth/ecscope"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/dhth/ecscope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fecscope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fecscope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fecscope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fecscope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhth","download_url":"https://codeload.github.com/dhth/ecscope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fecscope/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259545900,"owners_count":22874548,"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":["aws","aws-ecs","ecs","ecs-service","ecs-task","ratatui"],"created_at":"2025-06-13T08:10:11.975Z","updated_at":"2025-08-23T04:14:51.462Z","avatar_url":"https://github.com/dhth.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eecscope\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/dhth/ecscope/actions/workflows/main.yml\"\u003e\u003cimg alt=\"GitHub release\" src=\"https://img.shields.io/github/actions/workflow/status/dhth/ecscope/main.yml?style=flat-square\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://crates.io/crates/ecscope\"\u003e\u003cimg alt=\"GitHub release\" src=\"https://img.shields.io/crates/v/ecscope?style=flat-square\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/dhth/ecscope/releases/latest\"\u003e\u003cimg alt=\"Latest release\" src=\"https://img.shields.io/github/release/dhth/ecscope.svg?style=flat-square\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/dhth/ecscope/releases\"\u003e\u003cimg alt=\"Commits since latest release\" src=\"https://img.shields.io/github/commits-since/dhth/ecscope/latest?style=flat-square\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n`ecscope` lets you monitor AWS ECS resources from the terminal.\n\n![tui](https://tools.dhruvs.space/images/ecscope/ecscope.png)\n![web-2](https://tools.dhruvs.space/images/ecscope/web-2.png)\n\nIt does so by offering a [TUI](#-monitoring-tui) which shows services, tasks and\ncontainers in a single view. Instead of having to log into several accounts (or\nchange regions) via the AWS website, you're able to view relevant information\nfor ECS deployments in one place. You can group services by configuring them via\na \"profile\", and have `ecscope` load it up. Besides the TUI, `ecscope` can also\nshow deployments updates via a minimal [web interface](#web-ui).\n\n💾 Installation\n---\n\n**homebrew**:\n\n```sh\nbrew install dhth/tap/ecscope\n```\n\n**cargo**:\n\n```sh\ncargo install ecscope\n```\n\nOr get the binaries directly from a Github [release][1]. Read more about\nverifying the authenticity of released artifacts\n[here](#-verifying-release-artifacts).\n\n⚡️ Usage\n---\n\n```text\nUsage: ecscope [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  deps      List ECS deployments\n  profiles  Manage ecscope's profiles\n  monitor   Open monitoring TUI\n  help      Print this message or the help of the given subcommand(s)\n\nOptions:\n      --debug  Output debug information without doing anything\n  -h, --help   Print help\n```\n\n\u003cvideo src=\"https://github.com/user-attachments/assets/5abea06a-0749-4e5c-9ac8-3811c895a5c9\"\u003e\u003c/video\u003e\n\n📃 Profiles\n---\n\n### Adding a profile\n\nThe first thing you'll do after installing `ecscope` is to set up a profile. A\nprofile is simply configuration that groups together ECS resources you want to\nmonitor in one go. You set up a profile using:\n\n```bash\necscope profiles add \u003cPROFILE\u003e\n```\n\nThis will generate a TOML file in your config directory that looks like this:\n\n```toml\n[[clusters]]\nkeys = [\"\u003cKEY\u003e\"]\narn = \"arn:aws:ecs:eu-central-1:\u003cACCOUNT_ID\u003e:cluster/\u003cCLUSTER_NAME\u003e\"\nservices = [\n  \"service-a\",\n  \"service-b\"\n]\n# use this to provide configuration and credentials via environment variables\n# https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html\nconfig_source = \"env\"\n\n[[clusters]]\nkeys = [\"\u003cKEY\u003e\"]\narn = \"arn:aws:ecs:eu-central-1:\u003cACCOUNT_ID\u003e:cluster/\u003cCLUSTER_NAME\u003e\"\nservices = [\n  \"service-a\",\n  \"service-b\"\n]\n# use this to leverage a profile contained in the shared AWS config and credentials files\n# https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html\nconfig_source = \"profile:\u003cPROFILE_NAME\u003e\"\n\n[[clusters]]\nkeys = [\"\u003cKEY\u003e\"]\narn = \"arn:aws:ecs:eu-central-1:\u003cACCOUNT_ID\u003e:cluster/\u003cCLUSTER_NAME\u003e\"\nservices = [\n  \"service-a\",\n  \"service-b\"\n]\n# use this when you want to provide configuration and credentials via environment variables\n# but want to assume another role for performing the actual operations\nconfig_source = \"assume:\u003cIAM_ROLE_ARN\u003e\"\n```\n\n### Listing profiles\n\nYou can list configured profiles using `ecscope profiles list`.\n\n🛠 AWS Configuration\n---\n\n`ecscope` supports getting AWS configuration from the following sources:\n\n### Environment variables\n\nThis is configured by setting `config_source` to `\"env\"` in the profile config.\nThe following environment variables need to be set for this option.\n\n- AWS_ACCESS_KEY_ID\n- AWS_SECRET_ACCESS_KEY\n- AWS_SESSION_TOKEN\n- AWS_REGION\n\nRead more about this\n[here](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html).\n\n### Shared config\n\nUse this option when you want to leverage profiles set in the [shared AWS\nconfig](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) for\nauthentication and configuration.\n\n`ecscope` can be configured to use this option by setting `config_source` to\n`\"profile:\u003cPROFILE\u003e\"` in the profile config.\n\n⏳ Deployments\n---\n\nECS deployments can be viewed using the `deps` command.\n\n```text\n$ ecscope deps -h\n\nUsage: ecscope deps [OPTIONS] \u003cPROFILE\u003e\n\nArguments:\n  \u003cPROFILE\u003e  Profile to use\n\nOptions:\n  -s, --service-filter \u003cREGEX\u003e  Filtration query for service names\n  -k, --key-filter \u003cREGEX\u003e      Filtration query for cluster keys\n  -S, --state \u003cSTRING\u003e          Deployment state to query for [possible values: finished, in-progress, failing]\n  -c, --config-dir \u003cPATH\u003e       Config directory (to override ecscope's default config directory)\n  -f, --format \u003cSTRING\u003e         Format to use [default: json] [possible values: delimited, json, plain]\n      --debug                   Output debug information without doing anything\n  -m, --mode \u003cSTRING\u003e           Output mode [default: default] [possible values: default, web]\n      --web-skip-opening        Whether to skip opening web results in browser (when --mode=web)\n  -h, --help                    Print help (see more with '--help')\n```\n\n```bash\necscope deps \u003cPROFILE\u003e\n\n# filter by cluster keys\necscope deps \u003cPROFILE\u003e -k prod\n\n# filter by cluster keys\necscope deps \u003cPROFILE\u003e -k '(qa|prod)'\n\n# filter by service names\necscope deps \u003cPROFILE\u003e -s '.*-service'\n\n# only show deployments that are finished\necscope deps \u003cPROFILE\u003e --state finished\n\n# only show deployments that are pending\necscope deps \u003cPROFILE\u003e --state pending\n\n# only show deployments that are failing\necscope deps \u003cPROFILE\u003e --state failing\n```\n\nBy default, the `deps` command outputs results in the JSON format.\n\n\u003cdetails\u003e\u003csummary\u003e Sample output\u003c/summary\u003e\n\n```bash\necscope deps \u003cPROFILE\u003e -s auth\n```\n\n```json\n[\n  {\n    \"service_name\": \"authentication-service\",\n    \"keys\": \"qa\",\n    \"cluster_arn\": \"arn:aws:ecs:eu-central-1:\u003cREDACTED\u003e:cluster/authentication-service-infrastructure-qa\",\n    \"deployment_id\": \"ecs-svc/\u003cREDACTED\u003e\",\n    \"status\": \"PRIMARY\",\n    \"running_count\": 3,\n    \"desired_count\": 3,\n    \"pending_count\": 0,\n    \"failed_count\": 0\n  },\n  {\n    \"service_name\": \"authentication-service\",\n    \"keys\": \"staging\",\n    \"cluster_arn\": \"arn:aws:ecs:eu-central-1:\u003cREDACTED\u003e:cluster/authentication-service-infrastructure-staging\",\n    \"deployment_id\": \"ecs-svc/\u003cREDACTED\u003e\",\n    \"status\": \"PRIMARY\",\n    \"running_count\": 1,\n    \"desired_count\": 1,\n    \"pending_count\": 0,\n    \"failed_count\": 0\n  },\n  {\n    \"service_name\": \"authentication-service\",\n    \"keys\": \"prod\",\n    \"cluster_arn\": \"arn:aws:ecs:eu-central-1:\u003cREDACTED\u003e:cluster/authentication-service-infrastructure-prod\",\n    \"deployment_id\": \"ecs-svc/\u003cREDACTED\u003e\",\n    \"status\": \"PRIMARY\",\n    \"running_count\": 3,\n    \"desired_count\": 3,\n    \"pending_count\": 0,\n    \"failed_count\": 0\n  }\n]\n```\n\u003c/details\u003e\n\n### Tabular Output\n\nYou can view the output of `deps` command as a table as follows (uses\n[tbll](https://github.com/dhth/tbll)):\n\n```bash\necscope deps \u003cPROFILE\u003e -s auth -f delimited |\n    (read -r header \u0026\u0026 echo \"$header\" \u0026\u0026 sort) |\n    tbll -C 2,3\n```\n\n```text\n┌────────────────────────┬─────────┬─────────┬───────────────┬───────────────┬───────────────┬──────────────┐\n│ service_name           │ keys    │ status  │ running_count │ desired_count │ pending_count │ failed_count │\n├────────────────────────┼─────────┼─────────┼───────────────┼───────────────┼───────────────┼──────────────┤\n│ authentication-service │ prod    │ PRIMARY │ 3             │ 3             │ 0             │ 0            │\n│ authentication-service │ qa      │ PRIMARY │ 3             │ 3             │ 0             │ 0            │\n│ authentication-service │ staging │ PRIMARY │ 1             │ 1             │ 0             │ 0            │\n└────────────────────────┴─────────┴─────────┴───────────────┴───────────────┴───────────────┴──────────────┘\n```\n\n### Web UI\n\nDeployments can also be viewed through a web UI (using `--mode web`). This\nallows you to monitor deployment status in real time with a simple interface.\n\n![web](https://tools.dhruvs.space/images/ecscope/web.png)\n![web-2](https://tools.dhruvs.space/images/ecscope/web-2.png)\n\n📟 Monitoring TUI\n---\n\nOnce a profile is configured, you can begin monitoring ECS deployments via\n`ecscope`'s TUI.\n\n```text\n$ ecscope monitor -h\n\nUsage: ecscope monitor [OPTIONS] \u003cPROFILE\u003e\n\nArguments:\n  \u003cPROFILE\u003e  Profile to use\n\nOptions:\n  -s, --service-filter \u003cREGEX\u003e  Filtration query for service names\n  -k, --key-filter \u003cREGEX\u003e      Filtration query for cluster keys\n      --debug                   Output debug information without doing anything\n  -h, --help                    Print help\n```\n\nThe TUI displays running tasks for each configured service, along with their\nrespective containers. Additionally, details for the currently selected service,\ntask, and container are shown in dedicated panes to the right.\n\nThe TUI also supports refreshing of results — either on a schedule or manually.\nAdditionally, you can mark specific services to be targeted for the refresh.\n\n### TUI Reference Manual\n\n```text\nKeymaps\n---\n\nGeneral\n    ?                    show/hide help view\n    Esc / q              go back/exit\n    \u003cctrl+c\u003e             exit immediately\n\nMain View\n    j / ↓                go down in a list\n    k / ↑                go up in a list\n    H / ←                move to the pane to the left\n    J / Tab              move to the pane below\n    K / \u003cS-Tab\u003e          move to the pane above\n    L / →                move to the pane to the right\n    r                    refresh details for current item\n    \u003cc-r\u003e                refresh data (either the ones marked, or all)\n    R                    toggle auto refresh (for either the ones marked, or all)\n\nServices List\n    m                    mark service for auto refresh\n```\n\n### Filtering services to be monitored\n\nYou can filter services using two kinds of filter queries, one for the cluster\nkey and the other for the service name.\n\n```bash\n# will show all services that match a regex .*-service\necscope monitor profile -s '.*-service'\n# will show all services in clusters where a key matches the regex qa|staging\necscope monitor profile -k 'qa|staging'\n# combine both filters\necscope monitor profile -s '.*-service' -k 'qa'\n```\n\n🔐 Verifying release artifacts\n---\n\nIn case you get the `ecscope` binary directly from a [release][1], you may want\nto verify its authenticity. Checksums are applied to all released artifacts, and\nthe resulting checksum file is attested using [Github Attestations][2].\n\nSteps to verify (replace `A.B.C` in the commands below with the version you\nwant):\n\n1. Download the sha256 checksum file for your platform from the release:\n\n   ```shell\n   curl -sSLO https://github.com/dhth/ecscope/releases/download/vA.B.C/ecscope-x86_64-unknown-linux-gnu.tar.xz.sha256\n   ```\n\n2. Verify the integrity of the checksum file using [gh][3].\n\n   ```shell\n   gh attestation verify ecscope-x86_64-unknown-linux-gnu.tar.xz.sha256 --repo dhth/ecscope\n   ```\n\n3. Download the compressed archive you want, and validate its checksum:\n\n   ```shell\n   curl -sSLO https://github.com/dhth/ecscope/releases/download/vA.B.C/ecscope-x86_64-unknown-linux-gnu.tar.xz\n   sha256sum --ignore-missing -c ecscope-x86_64-unknown-linux-gnu.tar.xz.sha256\n   ```\n\n3. If checksum validation goes through, uncompress the archive:\n\n   ```shell\n   tar -xzf ecscope-x86_64-unknown-linux-gnu.tar.xz\n   cd ecscope-x86_64-unknown-linux-gnu\n   ./ecscope\n   # profit!\n   ```\n\n≈ Related tools\n---\n\n- [ecsv](https://github.com/dhth/ecsv) lets you quickly check the versions of\n  your systems running in ECS tasks across various environments\n\n[1]: https://github.com/dhth/ecscope/releases\n[2]: https://github.blog/news-insights/product-news/introducing-artifact-attestations-now-in-public-beta/\n[3]: https://github.com/cli/cli\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhth%2Fecscope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhth%2Fecscope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhth%2Fecscope/lists"}