# CloudSense
A CLI and interactive GUI for AWS cost tracking.
## Features
- **AWS cost tracking** using Cost Explorer API with authentication
- **Complete cost visibility** - entire account and per-service usage analysis
- **Intelligent caching** - persistent file-based caching with 1 hour duration (customizable) to minimize API costs
- **Flexible time ranges** - 7, 14, 30, 90 days, current month, previous month, custom month, specific day
- **Interactive visualizations** - daily cost trends with dynamic charts
- **Detailed breakdowns** - service-by-service cost analysis
- **Performance optimized** - AWS session caching and efficient API usage
- **Enterprise features** - rate limiting, input validation, security headers
- **Health monitoring** - built-in health check endpoint for monitoring
- **Logging levels and debug mode** - structured logging with configurable levels
## Caching cost data to reduce cost
AWS Cost Explorer API calls are $.01 for each call.
### Cache Behavior
- CloudSense caches cost data for **1 hour** (default, configurable) to reduce AWS API costs
- **Persistent file-based caching** stored in `~/.cloudsense-cache/`
- **Cross-session persistence** - cache survives CLI restarts
- Cache status displayed in CLI and web interface with last update timestamp
- Click **"Update Cost Data"** button or use `--force-refresh` to bypass cache
- CLI and GUI use the **same caching system** and share cached data
- Second call to same data (within cache timeout) uses cache instead of AWS API
**Practical Impact:**
```bash
# With persistent cache (by default 1 hour)
cloudsense --days 7 # API cost ($0.01)
cloudsense --days 7 # Same parameters, will uses cache with no API call (free)
```
**Cost Optimization Tips - Avoid Cost Explorer API calls when you can**
- Use **same time range** for multiple queries to benefit from caching
- **GUI sessions** cache multiple API calls (regions, services, breakdowns)
- **CLI repeated calls** with same parameters use cache within 1 hour
- Configure longer cache duration with `--cache-duration 7200` (2 hours)
- Use `--force-refresh` only when you need guaranteed fresh data
## Installation
**Recommended: Use a virtual environment**
```bash
# Create virtual environment
python -m venv cloudsense-env
# Activate virtual environment
source cloudsense-env/bin/activate
```
1. **Install CloudSense:**
```bash
pip install cloudsense
```
2. **Configure AWS credentials (Required):**
```bash
aws configure
# or set environment variables:
export AWS_ACCESS_KEY_ID=<your-key>
export AWS_SECRET_ACCESS_KEY=<your-secret>
export AWS_DEFAULT_REGION=us-east-1
```
**Authentication Required**: CloudSense requires valid AWS credentials to access cost data.
**API Region**: CloudSense always uses `us-east-1` for AWS Cost Explorer API calls (hardcoded, AWS requirement). Your AWS_DEFAULT_REGION setting does not affect the Cost Explorer API endpoint.
3. **Run CloudSense (CLI):**
```bash
cloudsense
```
**Example CLI Output:**
```
$ cloudsense --hide-acct
======================================================================
CloudSense - AWS Cost Report (30 days)
======================================================================
Account: ***HIDDEN***
Date Range: 2025-07-21 to 2025-08-20
Region: All Regions
Services: 16
Data Status: CACHED at 2025-08-20 12:22
----------------------------------------------------------------------
Service Breakdown:
----------------------------------------------------------------------
1. Amazon Registrar $ 88.00 ( 31.6%)
2. EC2 - Other $ 66.23 ( 23.7%)
├── EBS gp3 Storage ├── 10.03
├── EBS io2 IOPS ├── 4.25
├── EBS Snapshots ├── 3.23
├── EBS io1 IOPS ├── 1.18
├── EBS io1 Storage ├── 0.91
├── EBS io2 Storage ├── 0.35
├── NAT Gateway ├── 46.15
├── Spot Instances ├── 0.18
└── Data Transfer └── 0.13
3. EC2 - Compute $ 53.97 ( 19.4%)
4. AWS Cost Explorer $ 20.41 ( 7.3%)
5. Amazon Q $ 18.57 ( 6.7%)
6. Amazon S3 $ 9.87 ( 3.5%)
7. Amazon FSx $ 8.15 ( 2.9%)
8. VPC $ 5.65 ( 2.0%)
9. Bedrock: SD 3.5 Large $ 5.12 ( 1.8%)
10. Route53 $ 2.54 ( 0.9%)
11. Amazon EFS $ 0.21 ( 0.1%)
12. Bedrock: Claude Opus 4 $ 0.11 ( 0.0%)
13. Bedrock: Claude Sonnet 4 $ 0.04 ( 0.0%)
14. AWS Backup $ 0.02 ( 0.0%)
15. CloudWatch $ 0.00 ( 0.0%)
16. DynamoDB $ 0.00 ( 0.0%)
======================================================================
TOTAL COST: $ 278.88
======================================================================
```
4. **Launch Web Interface:**
```bash
cloudsense --gui
```
Then open http://localhost:8080 in your browser
**Security Note**: By default, CloudSense binds to `127.0.0.1` (localhost only) for security.
**GUI Startup Output**
```bash
Starting CloudSense on http://127.0.0.1:8080
Configuration: default
AWS Region: us-east-1
Cache Duration: 3600s
Log Level: INFO
Press Ctrl+C to stop the server
--------------------------------------------------
* Serving Flask app 'cloudsense.app'
* Debug mode: off
* Running on http://127.0.0.1:8080
```
## Command Line Usage
### Text Output (Default)
```bash
cloudsense # 30-day cost report (all regions by default)
cloudsense --days 7 # 7-day cost report
cloudsense --days 90 # 90-day cost report
cloudsense --hide-acct # Hide AWS account number
cloudsense --force-refresh # Force cache refresh
cloudsense --aws-region us-west-2 # Show costs for us-west-2 region only
cloudsense --aws-region global # Show global services only (IAM, Route53, etc.)
```
### Web Interface
```bash
cloudsense --gui # Launch web interface
cloudsense --gui --hide-acct # Launch web interface with hidden account
cloudsense --gui --port 5000 # Web interface on custom port
cloudsense --gui --host 0.0.0.0 # Web interface on all interfaces (security risk)
cloudsense --gui --debug # Web interface with debug mode
```
### Environment Configuration
```bash
# Copy environment template and customize
cp .env.example .env
# Available environment variables:
export AWS_REGION=us-east-1
export LOG_LEVEL=INFO
export CACHE_DURATION=3600
export RATELIMIT_DEFAULT="100 per hour"
export HIDE_ACCOUNT=false
```
CloudSense includes a built-in health check endpoint for monitoring and load balancer integration:
```bash
# Health check endpoint
curl http://localhost:8080/health
# Example response:
{
"status": "healthy",
"aws": "connected",
"timestamp": "2024-01-15T10:30:00Z",
"version": "0.1.1"
}
```
## Rate Limiting & Security
CloudSense implements comprehensive security measures:
- **Rate Limiting**: API endpoints are protected with configurable rate limits
- `/api/billing`: 30 requests per minute
- `/api/service/*`: 60 requests per minute
- `/api/regions`: 10 requests per minute
- **Input Validation**: All parameters are validated and sanitized
- **Security Headers**: Protection against XSS, clickjacking, and content sniffing
- **Error Handling**: Structured error responses without sensitive information leakage
- **Logging**: Comprehensive request and error logging for security monitoring
## AWS Permissions Required
Your AWS credentials need the following permissions:
**API Endpoint**: CloudSense hardcodes the `us-east-1` endpoint for AWS Cost Explorer API calls, as required by AWS. This is completely independent of your region filtering - you can still filter costs by any AWS region.
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ce:GetCostAndUsage",
"ce:GetUsageReport",
"sts:GetCallerIdentity"
],
"Resource": "*"
}
]
}
```
**Note**: `sts:GetCallerIdentity` is required for authentication validation and account ID display.
## Configuration Options
Create a `.env` file for local development:
```bash
# AWS Configuration
AWS_REGION=us-east-1
AWS_PROFILE=default
# Application Configuration
FLASK_DEBUG=true
LOG_LEVEL=DEBUG
CACHE_DURATION=3600
# Security Configuration
RATELIMIT_DEFAULT=1000 per hour # More lenient for development
HIDE_ACCOUNT=false
# Server Configuration
HOST=127.0.0.1
PORT=8080
```
## Logging
View detailed logs:
```bash
cloudsense --log-level DEBUG # Enable debug logging
tail -f cloudsense.log # Monitor log file
```
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "cloudsense",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "aws, cost, budget, cli, dashboard, monitoring, cloud, gui",
"author": "Veloduff",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/42/9c/5c209673c00132de98933d027d9e57929ea3699bfb81d74cb63480b56ca0/cloudsense-0.3.0.tar.gz",
"platform": null,
"description": "# CloudSense\n\nA CLI and interactive GUI for AWS cost tracking.\n\n## Features\n\n- **AWS cost tracking** using Cost Explorer API with authentication\n- **Complete cost visibility** - entire account and per-service usage analysis\n- **Intelligent caching** - persistent file-based caching with 1 hour duration (customizable) to minimize API costs\n- **Flexible time ranges** - 7, 14, 30, 90 days, current month, previous month, custom month, specific day\n- **Interactive visualizations** - daily cost trends with dynamic charts\n- **Detailed breakdowns** - service-by-service cost analysis \n- **Performance optimized** - AWS session caching and efficient API usage\n- **Enterprise features** - rate limiting, input validation, security headers\n- **Health monitoring** - built-in health check endpoint for monitoring\n- **Logging levels and debug mode** - structured logging with configurable levels\n\n\n## Caching cost data to reduce cost \n\nAWS Cost Explorer API calls are $.01 for each call.\n\n### Cache Behavior\n- CloudSense caches cost data for **1 hour** (default, configurable) to reduce AWS API costs\n- **Persistent file-based caching** stored in `~/.cloudsense-cache/`\n- **Cross-session persistence** - cache survives CLI restarts \n- Cache status displayed in CLI and web interface with last update timestamp\n- Click **\"Update Cost Data\"** button or use `--force-refresh` to bypass cache\n- CLI and GUI use the **same caching system** and share cached data\n- Second call to same data (within cache timeout) uses cache instead of AWS API\n\n\n**Practical Impact:**\n```bash\n# With persistent cache (by default 1 hour)\ncloudsense --days 7 # API cost ($0.01)\ncloudsense --days 7 # Same parameters, will uses cache with no API call (free)\n```\n\n**Cost Optimization Tips - Avoid Cost Explorer API calls when you can**\n- Use **same time range** for multiple queries to benefit from caching\n- **GUI sessions** cache multiple API calls (regions, services, breakdowns)\n- **CLI repeated calls** with same parameters use cache within 1 hour\n- Configure longer cache duration with `--cache-duration 7200` (2 hours)\n- Use `--force-refresh` only when you need guaranteed fresh data\n\n## Installation\n\n**Recommended: Use a virtual environment**\n```bash\n# Create virtual environment\npython -m venv cloudsense-env\n\n# Activate virtual environment\nsource cloudsense-env/bin/activate\n```\n\n1. **Install CloudSense:**\n ```bash\n pip install cloudsense\n ```\n\n2. **Configure AWS credentials (Required):**\n ```bash\n aws configure\n # or set environment variables:\n export AWS_ACCESS_KEY_ID=<your-key>\n export AWS_SECRET_ACCESS_KEY=<your-secret>\n export AWS_DEFAULT_REGION=us-east-1\n ```\n \n **Authentication Required**: CloudSense requires valid AWS credentials to access cost data.\n \n **API Region**: CloudSense always uses `us-east-1` for AWS Cost Explorer API calls (hardcoded, AWS requirement). Your AWS_DEFAULT_REGION setting does not affect the Cost Explorer API endpoint.\n\n3. **Run CloudSense (CLI):**\n ```bash\n cloudsense\n ```\n \n **Example CLI Output:**\n ```\n $ cloudsense --hide-acct\n ======================================================================\n CloudSense - AWS Cost Report (30 days)\n ======================================================================\n Account: ***HIDDEN***\n Date Range: 2025-07-21 to 2025-08-20\n Region: All Regions\n Services: 16\n Data Status: CACHED at 2025-08-20 12:22\n ----------------------------------------------------------------------\n Service Breakdown:\n ----------------------------------------------------------------------\n 1. Amazon Registrar $ 88.00 ( 31.6%)\n 2. EC2 - Other $ 66.23 ( 23.7%)\n \u251c\u2500\u2500 EBS gp3 Storage \u251c\u2500\u2500 10.03\n \u251c\u2500\u2500 EBS io2 IOPS \u251c\u2500\u2500 4.25\n \u251c\u2500\u2500 EBS Snapshots \u251c\u2500\u2500 3.23\n \u251c\u2500\u2500 EBS io1 IOPS \u251c\u2500\u2500 1.18\n \u251c\u2500\u2500 EBS io1 Storage \u251c\u2500\u2500 0.91\n \u251c\u2500\u2500 EBS io2 Storage \u251c\u2500\u2500 0.35\n \u251c\u2500\u2500 NAT Gateway \u251c\u2500\u2500 46.15\n \u251c\u2500\u2500 Spot Instances \u251c\u2500\u2500 0.18\n \u2514\u2500\u2500 Data Transfer \u2514\u2500\u2500 0.13\n 3. EC2 - Compute $ 53.97 ( 19.4%)\n 4. AWS Cost Explorer $ 20.41 ( 7.3%)\n 5. Amazon Q $ 18.57 ( 6.7%)\n 6. Amazon S3 $ 9.87 ( 3.5%)\n 7. Amazon FSx $ 8.15 ( 2.9%)\n 8. VPC $ 5.65 ( 2.0%)\n 9. Bedrock: SD 3.5 Large $ 5.12 ( 1.8%)\n 10. Route53 $ 2.54 ( 0.9%)\n 11. Amazon EFS $ 0.21 ( 0.1%)\n 12. Bedrock: Claude Opus 4 $ 0.11 ( 0.0%)\n 13. Bedrock: Claude Sonnet 4 $ 0.04 ( 0.0%)\n 14. AWS Backup $ 0.02 ( 0.0%)\n 15. CloudWatch $ 0.00 ( 0.0%)\n 16. DynamoDB $ 0.00 ( 0.0%)\n ======================================================================\n TOTAL COST: $ 278.88\n ======================================================================\n ```\n\n4. **Launch Web Interface:**\n ```bash\n cloudsense --gui\n ```\n Then open http://localhost:8080 in your browser\n \n **Security Note**: By default, CloudSense binds to `127.0.0.1` (localhost only) for security.\n\n **GUI Startup Output**\n\n ```bash\n Starting CloudSense on http://127.0.0.1:8080\n Configuration: default\n AWS Region: us-east-1\n Cache Duration: 3600s\n Log Level: INFO\n \n Press Ctrl+C to stop the server\n --------------------------------------------------\n * Serving Flask app 'cloudsense.app'\n * Debug mode: off\n * Running on http://127.0.0.1:8080\n ```\n \n\n \n\n\n## Command Line Usage\n\n### Text Output (Default)\n```bash\ncloudsense # 30-day cost report (all regions by default)\ncloudsense --days 7 # 7-day cost report \ncloudsense --days 90 # 90-day cost report\ncloudsense --hide-acct # Hide AWS account number\ncloudsense --force-refresh # Force cache refresh\ncloudsense --aws-region us-west-2 # Show costs for us-west-2 region only\ncloudsense --aws-region global # Show global services only (IAM, Route53, etc.)\n```\n\n### Web Interface\n```bash\ncloudsense --gui # Launch web interface\ncloudsense --gui --hide-acct # Launch web interface with hidden account\ncloudsense --gui --port 5000 # Web interface on custom port\ncloudsense --gui --host 0.0.0.0 # Web interface on all interfaces (security risk)\ncloudsense --gui --debug # Web interface with debug mode\n```\n\n\n### Environment Configuration\n```bash\n# Copy environment template and customize\ncp .env.example .env\n\n# Available environment variables:\nexport AWS_REGION=us-east-1\nexport LOG_LEVEL=INFO\nexport CACHE_DURATION=3600\nexport RATELIMIT_DEFAULT=\"100 per hour\"\nexport HIDE_ACCOUNT=false\n```\n\nCloudSense includes a built-in health check endpoint for monitoring and load balancer integration:\n\n```bash\n# Health check endpoint\ncurl http://localhost:8080/health\n\n# Example response:\n{\n \"status\": \"healthy\",\n \"aws\": \"connected\", \n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"version\": \"0.1.1\"\n}\n```\n\n## Rate Limiting & Security\n\nCloudSense implements comprehensive security measures:\n\n- **Rate Limiting**: API endpoints are protected with configurable rate limits\n - `/api/billing`: 30 requests per minute\n - `/api/service/*`: 60 requests per minute \n - `/api/regions`: 10 requests per minute\n- **Input Validation**: All parameters are validated and sanitized\n- **Security Headers**: Protection against XSS, clickjacking, and content sniffing\n- **Error Handling**: Structured error responses without sensitive information leakage\n- **Logging**: Comprehensive request and error logging for security monitoring\n\n## AWS Permissions Required\n\nYour AWS credentials need the following permissions:\n\n**API Endpoint**: CloudSense hardcodes the `us-east-1` endpoint for AWS Cost Explorer API calls, as required by AWS. This is completely independent of your region filtering - you can still filter costs by any AWS region.\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ce:GetCostAndUsage\",\n \"ce:GetUsageReport\",\n \"sts:GetCallerIdentity\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n**Note**: `sts:GetCallerIdentity` is required for authentication validation and account ID display.\n\n\n## Configuration Options\n\nCreate a `.env` file for local development:\n\n```bash\n# AWS Configuration\nAWS_REGION=us-east-1\nAWS_PROFILE=default\n\n# Application Configuration \nFLASK_DEBUG=true\nLOG_LEVEL=DEBUG\nCACHE_DURATION=3600\n\n# Security Configuration\nRATELIMIT_DEFAULT=1000 per hour # More lenient for development\nHIDE_ACCOUNT=false\n\n# Server Configuration\nHOST=127.0.0.1\nPORT=8080\n```\n\n## Logging\n\nView detailed logs:\n```bash\ncloudsense --log-level DEBUG # Enable debug logging\ntail -f cloudsense.log # Monitor log file\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI and interactive GUI for AWS cost tracking.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/veloduff/cloudsense",
"Issues": "https://github.com/veloduff/cloudsense/issues",
"Repository": "https://github.com/veloduff/cloudsense"
},
"split_keywords": [
"aws",
" cost",
" budget",
" cli",
" dashboard",
" monitoring",
" cloud",
" gui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c738a88e01e7c3c2cd9fdb5d7b4833117cf3776df773cfbb571f00c631731110",
"md5": "bbd5239cd7ba22e343518510e27d6a5e",
"sha256": "5389c13337c8dbca93f3211989ed64c496c85a6cbe9e5133f106033e4a69111e"
},
"downloads": -1,
"filename": "cloudsense-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bbd5239cd7ba22e343518510e27d6a5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 41985,
"upload_time": "2025-08-22T15:51:17",
"upload_time_iso_8601": "2025-08-22T15:51:17.623461Z",
"url": "https://files.pythonhosted.org/packages/c7/38/a88e01e7c3c2cd9fdb5d7b4833117cf3776df773cfbb571f00c631731110/cloudsense-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "429c5c209673c00132de98933d027d9e57929ea3699bfb81d74cb63480b56ca0",
"md5": "0c7288133225e1fe9b72bcb4df739025",
"sha256": "cf0882ead91b92a067b5b7a8d30856cbb8e982c9eb57ad8500ee741ea51a94e8"
},
"downloads": -1,
"filename": "cloudsense-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "0c7288133225e1fe9b72bcb4df739025",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 41432,
"upload_time": "2025-08-22T15:51:18",
"upload_time_iso_8601": "2025-08-22T15:51:18.781130Z",
"url": "https://files.pythonhosted.org/packages/42/9c/5c209673c00132de98933d027d9e57929ea3699bfb81d74cb63480b56ca0/cloudsense-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 15:51:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "veloduff",
"github_project": "cloudsense",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "flask",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "boto3",
"specs": [
[
">=",
"1.26.0"
]
]
},
{
"name": "flask-limiter",
"specs": [
[
">=",
"3.3.0"
]
]
},
{
"name": "Werkzeug",
"specs": [
[
">=",
"3.0.0"
]
]
}
],
"lcname": "cloudsense"
}
JSON
