Skip to content

Quick Start (Local)

Scan your cloud account from your laptop in under 5 minutes.

1. Install

From PyPI (recommended):

python3 -m venv .venv && source .venv/bin/activate
pip install argus-cloud-optimizer
argus --version   # argus x.y.z

Why a virtual environment?

On macOS Sonoma/Sequoia and most modern Linux distros, pip install without a venv fails with externally-managed-environment. The two-line pattern above works everywhere and avoids the --break-system-packages flag.

From source (for development):

git clone https://github.com/vamshisiddarth/argus.git
cd argus
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

2. Configure

cp .env.example .env

Open .env and set the minimum required values. Pick the tab for your cloud:

.env
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...        # get from console.anthropic.com

PRIMARY_REGION=us-east-1
RESOURCE_EXPLORER_REGION=us-east-1

DRY_RUN=true

Resource Explorer aggregator index

Argus uses AWS Resource Explorer to discover all resources. You need an aggregator index in PRIMARY_REGION.

Check if you have one: 

aws resource-explorer-2 get-index --region us-east-1

If not, create one: 

aws resource-explorer-2 create-index --type LOCAL --region us-east-1
aws resource-explorer-2 update-index-type --type AGGREGATOR --region us-east-1

AWS Cost Explorer — one-time activation

Argus uses Cost Explorer for per-resource cost data. If you've never enabled it:

  1. AWS Console → Billing and Cost Management → Cost Explorer
  2. Click Enable Cost Explorer
  3. Wait up to 24 hours for data to populate

Your first scan may show $0.00 cost on all findings until data is available. This is expected — metrics and last-activity signals still work normally.

.env
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

GCP_PROJECT_ID=my-project-123

DRY_RUN=true

GCP Application Default Credentials — quota project

After gcloud auth application-default login, run one more command: 

gcloud auth application-default set-quota-project YOUR_PROJECT_ID
Without this, the Cloud Asset Inventory API call fails with a cryptic PERMISSION_DENIED error even when your credentials are valid.

BigQuery billing export

Argus uses BigQuery billing export for cost data. Enable billing export and set BILLING_BQ_TABLE in .env. Without it, cost fields show $0.00 — metrics and activity still work.

.env
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

AZURE_SUBSCRIPTION_IDS=sub-id-1,sub-id-2

DRY_RUN=true

Azure authentication

Argus uses DefaultAzureCredential. Run az login before scanning.

3. Run your first scan

Argus auto-detects your cloud from environment variables, or specify explicitly:

argus scan --dry-run                  # auto-detects cloud
argus scan --cloud aws --dry-run      # explicit
argus scan --cloud gcp --dry-run
argus scan --cloud azure --dry-run

The agent will:

  1. Discover all billable resources via the cloud's discovery API
  2. Investigate candidates — metrics, cost data, and last-activity timestamps
  3. Print the notification payload to stdout (because DRY_RUN=true)

Typical output:

INFO  scan_start cloud=aws ignore_regions=[] primary_region=us-east-1 mode=single
INFO  agent_iteration iteration=1
INFO  tool_executed tool=list_resources is_error=False
INFO  agent_iteration iteration=2
INFO  tool_executed tool=get_cost is_error=False
...
INFO  agent_complete findings_count=4
INFO  scan_complete findings=4 total_waste_usd=42.65

Local reports are saved automatically

Every scan — including dry-run — saves two files locally:

local_reports/<cloud>/YYYY/MM/DD/<scan-id>.json   # full findings + metrics
local_reports/<cloud>/YYYY/MM/DD/<scan-id>.html   # human-readable report

Open the HTML file in a browser to review results without posting to Slack. This is especially useful when iterating on configuration or debugging findings.

Scan history and week-over-week diff

Argus compares each scan against the previous one and adds a scan_diff block to the JSON report:

"scan_diff": {
  "new_findings": 3,
  "recurring_findings": 2,
  "resolved_findings": 1
}

A finding is resolved when it no longer appears in the current scan. Recurring means it was flagged in the previous scan too — useful for tracking resources that teams are slow to act on.

4. Post to Slack

Once you're happy with the output, set your webhook URL and remove --dry-run:

.env
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../...
DRY_RUN=false

argus scan

Argus posts a compact digest — stats, a 2-sentence AI summary, and the top 5 findings as single lines. The full AI reasoning (why each resource is idle, what to do) lives in a separate HTML report.

Optional: HTML report with "Full report" button

To get the Full report button in the Slack digest, Argus needs an S3 bucket to upload the HTML report to.

  • Lambda deployment — the SAM template creates the bucket automatically (argus-reports-{accountId}-{region}) and sets REPORT_S3_BUCKET in the Lambda environment. Nothing to configure.

  • Local CLI runs — create a bucket manually and set it in .env:

    .env
    REPORT_S3_BUCKET=my-argus-reports-bucket

    Your local AWS credentials need s3:PutObject and s3:GetObject on that bucket.

The digest still posts to Slack without a bucket — it just won't have the button.

5. Interactive chat mode

Ask questions about your infrastructure in natural language instead of running a full scan:

pip install argus-cloud-optimizer[chat]   # optional: adds rich formatting
argus chat                               # auto-detects cloud
argus chat --cloud aws                   # or specify explicitly

Argus vx.y.z — AI Cloud Detective
Cloud: AWS | Accounts: my-account (123456789012)
Type your question, or /help for commands.

argus> What are my top 3 wastes?

Based on your AWS account, the three largest idle resources are:

1. NAT Gateway nat-0abc123 in us-east-1 — $32.50/mo
   Only 847 bytes transferred in 90 days. Recommendation: delete.
...

argus> Tell me more about that NAT Gateway

Available commands: /help, /scan, /cost, /clear, /quit

CLI reference

argus scan  [--cloud aws|gcp|azure] [options]   # full batch scan
argus chat  [--cloud aws|gcp|azure] [options]   # interactive Q&A
argus --run-now --cloud aws [options]           # backward-compat alias

Options:
  --cloud CLOUD              Cloud provider (auto-detected from env vars if omitted)
  --dry-run                  Print notification payload instead of posting
  --ignore-regions REGIONS   Comma-separated regions to skip
                             e.g. --ignore-regions ap-east-1,me-south-1
  --ai-provider PROVIDER     anthropic | bedrock | vertexai | azure_openai (default: anthropic)
  --accounts PATH            Path to accounts.yaml for multi-account mode
  --primary-region REGION    AWS region for boto3 session (default: us-east-1)
  --llm-budget USD           Cost budget per scan/session (default: $2.00 scan, $1.00 chat)

Next steps