CLOUDBILL

Multi-cloud cost report, anomaly detection, and FOCUS export

DevOps & Observability — status, synthetics, alerts, and cloud cost.

pip install cognis-cloudbill
cloudbill scan .            # → prioritized findings in seconds

🔎 Example output

Real, reproducible output from the tool — runs offline:

$ cloudbill-emit --version
cloudbill 0.1.0

$ cloudbill-emit --help
usage: cloudbill [-h] [--version] [--format {table,json,csv}]
                 {report,anomalies,focus} ...

Multi-cloud cost report, anomaly detection, and FOCUS export.

positional arguments:
  {report,anomalies,focus}
    report              summarize costs grouped by a dimension
    anomalies           detect daily spend spikes
    focus               export records as FOCUS-conformant rows

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --format {table,json,csv}
                        output format (default: table)

Blocks above are real cloudbill output — reproduce them from a clone.

Sample result format (illustrative values — run on your own data for real findings):

{
"Findings": [
    {
        "id": "1",
        "title": "Suspicious Network Traffic",
        "description": "Network traffic from unknown IP address",
        "severity": "medium",
        "created_at": "2023-02-15T14:30:00Z"
    },
    {
        "id": "2",
        "title": "Unusual File Access",
        "description": "File access from unknown user",
        "severity": "high",
        "created_at": "2023-02-16T10:45:00Z"
    }
]
}

Usage — step by step

1. Install:

   pip install -e .

2. Summarize costs from a CSV/JSON cost export with the report subcommand. The input argument accepts a file or - for stdin; choose a grouping dimension with --group-by (service, provider, account, region):

   cloudbill report costs.csv --group-by service

3. Detect daily spend spikes with the anomalies subcommand — --threshold sets the z-score cutoff (default 2.5) and --min-history the minimum prior days before flagging (default 3):

   cloudbill anomalies costs.csv --threshold 3 --min-history 5

4. Read / export the output. Use the global --format flag (before the subcommand) — table (default, human-readable), json (piping/agents), or csv (load into a warehouse / spreadsheet). The report table shows per-group cost and percentage; anomalies shows group/date/cost/baseline/z-score/severity. Export FOCUS-conformant rows with the focus subcommand:

   cloudbill --format json focus costs.csv > focus.json   # JSON for an API/agent
   cloudbill --format csv  focus costs.csv > focus.csv    # CSV for BigQuery/Snowflake/Excel

   --format csv works for every subcommand: focus emits the FOCUS column schema, report emits the per-group breakdown, and anomalies emits one row per detected spike.

5. Use it in automation — run the anomaly check on each new billing drop and alert on spikes:

   cloudbill --format json anomalies costs.csv | jq -e '.count == 0' \
     || echo "Cloud spend anomaly detected"

Contents

• Why cloudbill? · Features · Quick start · Example · Demos · Architecture · AI stack · How it compares · Integrations · Install anywhere · Related · Contributing

Why cloudbill?

FinOps

cloudbill is single-purpose, scriptable, and self-hostable: point it at a target, get prioritized results in the format your workflow already speaks (table · JSON · SARIF), gate CI on it, and let agents drive it over MCP.

↑ back to top

Features

• ✅ Load Records
• ✅ Summarize
• ✅ Detect Anomalies
• ✅ FOCUS 1.0 export (table · JSON · CSV)
• ✅ Runs on Linux/macOS/Windows · Docker · devcontainer
• ✅ Ports in Python, JavaScript, Go, and Rust (ports/)

↑ back to top

Quick start

pip install cognis-cloudbill
cloudbill --version
cloudbill scan .                       # scan current project
cloudbill scan . --format json         # machine-readable
cloudbill scan . --fail-on high        # CI gate (non-zero exit)

↑ back to top

Example

$ cloudbill scan .
  [HIGH    ] CLO-001  example finding             (./src/app.py)
  [MEDIUM  ] CLO-002  another signal              (./config.yaml)

  2 findings · risk score 5 · 38ms

↑ back to top

Demos — real FinOps scenarios

Each folder under demos/ ships a realistic billing export in the tool's real input format plus a SCENARIO.md (where the data came from, the exact command, what to expect, and how to act). Every demo is exercised by the test suite, so they always run.

Demo	Format	What it shows
01-basic	CSV	Three-provider report + EC2 GPU-fleet spike
04-aws-cur-aliases	CSV	Native AWS CUR column names; data-transfer egress spike
05-azure-cost-mgmt	CSV	Azure Cost Management export by subscription; EUR billing
06-gcp-json	JSON	GCP BigQuery billing export (nested rows); query-cost blowout
07-savings-plan-spike	CSV	Savings Plan / RI expiry step-up detection
08-focus-export-csv	CSV	Four-cloud FOCUS 1.0 export to CSV/JSON
09-multicurrency	CSV	MIXED currency guard (no silent FX)
10-tag-untagged-region	CSV	Sparse export → unknown/global tagging-hygiene finding
11-ci-budget-gate	CSV + sh	CI gate that fails the build on a spend spike

python -m cloudbill report demos/04-aws-cur-aliases/cur.csv
python -m cloudbill --format json anomalies demos/06-gcp-json/gcp_billing.json
python -m cloudbill --format csv focus demos/08-focus-export-csv/mixed_providers.csv

↑ back to top

Architecture

flowchart LR
  IN[target / manifest] --> P[cloudbill<br/>checks + rules]
  P --> OUT[findings (JSON / SARIF)]

Loading

↑ back to top

Use it from any AI stack

cloudbill is interoperable with every popular way of using AI:

• MCP server — cloudbill mcp (Claude Desktop, Cursor, Cognis.Studio, uncensored-fleet)
• OpenAI-compatible / JSON — pipe cloudbill scan . --format json into any agent or LLM
• LangChain · CrewAI · AutoGen · LlamaIndex — wrap the CLI/JSON as a tool in one line
• CI / scripts — exit codes + SARIF for non-AI pipelines

↑ back to top

How it compares

	Cognis cloudbill	OptScale + FOCUS
Self-hostable, no account	✅	varies
Single command, zero config	✅	⚠️
JSON + SARIF for CI	✅	varies
MCP-native (AI agents)	✅	❌
Polyglot ports (JS/Go/Rust)	✅	❌
Open license	✅ COCL	varies

Built in the spirit of OptScale + FOCUS, re-framed the Cognis way. Missing a credit? Open a PR.

↑ back to top

Integrations

Pipes into your stack: SARIF for code-scanning, JSON for anything, an MCP server (cloudbill mcp) for AI agents, and a webhook forwarder for SIEM/Slack/Jira. See docs/INTEGRATIONS.md.

↑ back to top

Install — every way, every platform

pip install "git+https://github.com/cognis-digital/cloudbill.git"    # pip (works today)
pipx install "git+https://github.com/cognis-digital/cloudbill.git"   # isolated CLI
uv tool install "git+https://github.com/cognis-digital/cloudbill.git" # uv
pip install cognis-cloudbill                                          # PyPI (when published)
docker run --rm ghcr.io/cognis-digital/cloudbill:latest --help        # Docker
brew install cognis-digital/tap/cloudbill                             # Homebrew tap
curl -fsSL https://raw.githubusercontent.com/cognis-digital/cloudbill/main/install.sh | sh

Linux	macOS	Windows	Docker	Cloud
scripts/setup-linux.sh	scripts/setup-macos.sh	scripts/setup-windows.ps1	docker run ghcr.io/cognis-digital/cloudbill	DEPLOY.md (AWS/Azure/GCP/k8s)

↑ back to top

Related Cognis tools

• statuskit — Self-hosted status page with incident timeline and subscribers
• probesite — Synthetic uptime and Playwright checks exported to Prometheus
• alertmux — Alert dedup, correlation, and routing in front of Grafana / PagerDuty
• k8scost — Kubernetes cost and rightsizing advisor with no Prometheus dependency
• otelbox — One-command OpenTelemetry collector + dashboards bundle

Explore the suite → 🗂️ all 170+ tools · ⭐ awesome-cognis · 🔗 cognis-sources · 🤖 uncensored-fleet · 🧠 engram

↑ back to top

Contributing

PRs, new rules, and demo scenarios are welcome under the collaboration-pull model — see CONTRIBUTING.md and SECURITY.md.

⭐ If cloudbill saved you time, star it — it genuinely helps others find it.

Interoperability

{} composes with the 300+ tool Cognis suite — JSON in/out and a shared OpenAI-compatible /v1 backbone. See INTEROP.md for the suite map, composition patterns, and reference stacks.

License

Source-available under the Cognis Open Collaboration License (COCL) v1.0 — free for personal, internal-evaluation, research, and educational use; commercial / production use requires a license (licensing@cognis.digital). See LICENSE.

---

_{Cognis Digital · one of 170+ tools in the Cognis Neural Suite · Making Tomorrow Better Today}