{"id":18525829,"url":"https://github.com/toricls/acos","last_synced_at":"2025-04-09T12:31:36.535Z","repository":{"id":61629232,"uuid":"537728641","full_name":"toricls/acos","owner":"toricls","description":"An interactive CLI tool to retrieve and show your AWS costs 💸","archived":false,"fork":false,"pushed_at":"2023-08-13T04:02:36.000Z","size":379,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T05:35:18.549Z","etag":null,"topics":["aws-billing","aws-cost","cli","go"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toricls.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}},"created_at":"2022-09-17T07:09:38.000Z","updated_at":"2025-02-20T19:19:31.000Z","dependencies_parsed_at":"2024-11-06T17:50:38.435Z","dependency_job_id":"cd7c3609-537c-41b6-aff2-1e98fb28ca71","html_url":"https://github.com/toricls/acos","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toricls%2Facos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toricls%2Facos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toricls%2Facos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toricls%2Facos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toricls","download_url":"https://codeload.github.com/toricls/acos/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248040351,"owners_count":21037849,"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-billing","aws-cost","cli","go"],"created_at":"2024-11-06T17:47:10.397Z","updated_at":"2025-04-09T12:31:31.508Z","avatar_url":"https://github.com/toricls.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# acos\n\n`acos` is an interactive CLI tool to retrieve and show your AWS costs using AWS Organizations and AWS Cost Explorer APIs 💸\n\n![acos demo](acos-demo.gif)\n\n## Prerequisites\n\n`acos` by default uses AWS Organizations and AWS Cost Explorer APIs, so that it requires the following AWS IAM permissions to retrieve cost related data.\n\n- [ce:GetCostAndUsage](https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/API_GetCostAndUsage.html) [^1]\n- [organizations:ListAccounts](https://docs.aws.amazon.com/organizations/latest/APIReference/API_ListAccounts.html) [^2]\n\nWith the `--ou` option, it requires `organizations:ListAccountsForParent` IAM permission _instead of_ `organizations:ListAccounts`.\n\n- [organizations:ListAccountsForParent](https://docs.aws.amazon.com/organizations/latest/APIReference/API_ListAccountsForParent.html) [^2]\n\n[^1]: Make sure you also have [AWS Cost Explorer](https://console.aws.amazon.com/cost-management/home) enabled and have [IAM access to the billing data](https://console.aws.amazon.com/billing/home#/account) activated using your root user credentials beforehand. See also the [docs to enable Cost Explorer for AWS Organizational accounts](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-access.html#ce-iam-users), and the [docs to activate IAM access to the billing data](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_billing.html).\n\n[^2]: `acos` falls back to using (1) [sts:GetCallerIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html) and (2) [iam:ListAccountAliases](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListAccountAliases.html) to retrieve your AWS account ID and alias, in case `organizations:ListAccounts` fails. This should happen when the AWS account you're accessing via `acos` is not part of an AWS Organization, and/or you don't have sufficient permissions to use the AWS Organizations APIs.\n\n## Installation\n\n```shell\n$ go install github.com/toricls/acos/cmd/acos@latest\n```\n\n## Usage\n\n```shell\n$ acos --help\nUsage of acos:\n  -accountIds string\n    \tOptional - Comma-separated AWS account IDs to retrieve costs. The interactive account selector is skipped when this flag is set.\n  -asOf string\n    \tOptional - The date to retrieve the cost data. The format should be 'YYYY-MM-DD'. The default value is today in UTC.\n  -comparedTo string\n    \tOptional - The cost of this month will be compared to either one of 'YESTERDAY' or 'LAST_WEEK'. This flag is ignored when the -json flag is set. (default \"YESTERDAY\")\n  -json\n    \tOptional - Print JSON instead of a table.\n  -ou string\n    \tOptional - The ID of an AWS Organizational Unit (OU) or Root to list direct-children AWS accounts. It must start with 'ou-' or 'r-' prefix. This flag is ignored when the -accountIds flag is set.\n```\n\n### Accounts within AWS Organization\n\n```shell\n$ acos\n? Select accounts: 567890123456 - my-prod, 123456789012 - my-sandbox\n+--------------+--------------+----------------+------------------+----------------+\n|  ACCOUNT ID  | ACCOUNT NAME | THIS MONTH ($) | VS YESTERDAY ($) | LAST MONTH ($) |\n+--------------+--------------+----------------+------------------+----------------+\n| 123456789012 | my-sandbox   |       0.038331 |       + 0.002255 |       0.127884 |\n| 567890123456 | my-prod      |    5820.334869 |     + 324.526062 |   10765.384186 |\n+--------------+--------------+----------------+------------------+----------------+\n|                       TOTAL |    5820.373201 |     + 324.528317 |   10765.512070 |\n+--------------+--------------+----------------+------------------+----------------+\nAs of 2023-07-18.\n```\n\n### Accounts under specific AWS Organizational Unit (OU)\n\nUse `--ou` option to filter selectable AWS accounts by specific OU. Note that the `--ou` option is ignored when the `--accountIds` option is set.\n\n```shell\n\n```shell\n$ acos --ou ou-xxxx-12345678\nRetrieving AWS accounts under the OU 'ou-xxxx-12345678'...\n? Select accounts: 234567890123 - my-dev, 123456789012 - my-sandbox\n+--------------+--------------+----------------+------------------+----------------+\n|  ACCOUNT ID  | ACCOUNT NAME | THIS MONTH ($) | VS YESTERDAY ($) | LAST MONTH ($) |\n+--------------+--------------+----------------+------------------+----------------+\n| 123456789012 | my-sandbox   |       0.038331 |       + 0.002255 |       0.127884 |\n| 234567890123 | my-dev       |     420.102431 |      + 25.801012 |     980.440598 |\n+--------------+--------------+----------------+------------------+----------------+\n|                       TOTAL |     420.140762 |      + 25.803267 |     980.568482 |\n+--------------+--------------+----------------+------------------+----------------+\nAs of 2023-07-18.\n```\n\n### Specific AWS accounts\n\nUse `--accountIds` option to retrieve costs for specific AWS accounts.\n\n```shell\n% ./dist/acos --accountIds 123456789012,567890123456\nAccount IDs specified. Retrieving accounts information...\n+--------------+--------------+----------------+------------------+----------------+\n|  ACCOUNT ID  | ACCOUNT NAME | THIS MONTH ($) | VS YESTERDAY ($) | LAST MONTH ($) |\n+--------------+--------------+----------------+------------------+----------------+\n| 123456789012 | my-sandbox   |       0.038331 |       + 0.002255 |       0.127884 |\n| 567890123456 | my-prod      |    5820.334869 |     + 324.526062 |   10765.384186 |\n+--------------+--------------+----------------+------------------+----------------+\n|                       TOTAL |    5820.373201 |     + 324.528317 |   10765.512070 |\n+--------------+--------------+----------------+------------------+----------------+\nAs of 2023-07-18.\n```\n\nThe `--json` option would be the best fit here because the `--accountIds` option skips the interactive account selector. You may use this combination of options to retrieve costs in a machine-readable format on a cron'd regular basis for example.\n\n```shell\n# Using --accountIds and --json options\n% ./dist/acos --accountIds 123456789012,567890123456 --json | jq .\n{\n  \"AsOf\": \"2023-07-18T14:18:00.182227402Z\",\n  \"Costs\": [\n    {\n      \"AccountID\": \"123456789012\",\n      \"AccountName\": \"my-sandbox\",\n      \"LatestDailyCostIncrease\": 0.0022556669922,\n      \"LatestWeeklyCostIncrease\": 0.0091031111333,\n      \"AmountLastMonth\": 0.127884116211,\n      \"AmountThisMonth\": 0.0383317958984\n    },\n    {\n      \"AccountID\": \"567890123456\",\n      \"AccountName\": \"my-prod\",\n      \"LatestDailyCostIncrease\": 324.526062214416504,\n      \"LatestWeeklyCostIncrease\": 1621.45464324951172,\n      \"AmountLastMonth\": 10765.3841868930054,\n      \"AmountThisMonth\": 5820.3348696633911\n    }\n  ]\n}\n```\n\n## Todo\n\n- Add some tests\n- ~Support OU-based accounts listing~ done\n- ~Support command arguments~, configuration file, and/or env vars for repeated use\n- ~Support JSON format output for piped commands chaining~ done\n\n## Contribution\n\n1. Fork ([https://github.com/toricls/acos/fork](https://github.com/toricls/acos/fork))\n4. Create a feature branch\n5. Commit your changes\n6. Rebase your local changes against the main branch\n7. Create a new Pull Request (use [conventional commits] for the title please)\n\n[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/\n\n## Licence\n\nDistributed under the [Apache-2.0](./LICENSE) license.\n\n## Author\n\n[Tori](https://github.com/toricls)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoricls%2Facos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoricls%2Facos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoricls%2Facos/lists"}