snowglobe-cli 0.1.0__tar.gz

snowglobe_cli-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+Copyright 2025 Jaryd Thornton
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

snowglobe_cli-0.1.0/PKG-INFO

@@ -0,0 +1,368 @@
+Metadata-Version: 2.4
+Name: snowglobe-cli
+Version: 0.1.0
+Summary: Explainable cost and access visibility for Snowflake
+Author-email: Jaryd Thornton <jaryd90@gmail.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography==45.0.5
+Requires-Dist: Jinja2==3.1.6
+Requires-Dist: pandas==2.3.1
+Requires-Dist: prompt_toolkit>=3.0.0
+Requires-Dist: pydantic==2.11.7
+Requires-Dist: pyOpenSSL==25.1.0
+Requires-Dist: PyYAML==6.0.2
+Requires-Dist: rich==14.0.0
+Requires-Dist: snowflake_connector_python==3.16.0
+Requires-Dist: sqlglot==27.1.0
+Requires-Dist: typer==0.16.0
+Requires-Dist: typing_extensions==4.14.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: tui
+Requires-Dist: textual>=0.80; extra == "tui"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.svg" alt="Snowglobe" width="600"/>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/snowglobe-cli/"><img src="https://img.shields.io/pypi/v/snowglobe-cli" alt="PyPI version"/></a>
+  <a href="https://pypi.org/project/snowglobe-cli/"><img src="https://img.shields.io/pypi/pyversions/snowglobe-cli" alt="Python versions"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"/></a>
+</p>
+
+<p align="center">
+  <strong>Explainable cost and access visibility for Snowflake — read-only by design.</strong>
+</p>
+
+Snowglobe helps analytics, data platform, and security teams answer three questions about their Snowflake account:
+
+1. **Where did our Snowflake spend come from?**
+2. **Who owns and can access what?**
+3. **Who is responsible when cost or access looks wrong?**
+
+It observes, explains, and recommends — and it never writes to your account.
+
+---
+
+## Table of contents
+
+- [Three ways to use it](#three-ways-to-use-it)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Quickstart](#quickstart)
+- [Features](#features)
+- [The TUI](#the-tui)
+- [The interactive shell](#the-interactive-shell)
+- [Headless CLI](#headless-cli)
+- [Security](#security)
+- [Limitations](#limitations)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Three ways to use it
+
+| Interface | Command | When to use it |
+|---|---|---|
+| **TUI** *(default)* | `snowglobe` | Day-to-day exploration. Seven screens, mouse + keyboard, optional vim navigation, theme switcher. |
+| **Interactive shell** | `snowglobe shell` | Wizards and quick lookups in a REPL. Useful when you only want one or two checks. |
+| **Headless CLI** | `snowglobe <subcommand>` | CI, cron jobs, scripts, piping into other tools. Outputs `table`, `json`, or `csv` per command. |
+
+All three share the same local SQLite cache and the same service layer, so anything you do in one is reflected in the others.
+
+---
+
+## Installation
+
+```bash
+pip install 'snowglobe-cli[tui]'    # includes the Textual TUI (recommended)
+pip install snowglobe-cli           # CLI + shell only, no Textual dependency
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/jcolethornton/snowglobe.git
+cd snowglobe
+pip install -e '.[tui]'
+```
+
+---
+
+## Requirements
+
+- Python **3.12+**
+- A Snowflake account
+- A Snowflake role with `IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` (grants read access to `ACCOUNT_USAGE`)
+- Optionally: `IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` for `ORGANIZATION_USAGE` to get your contracted storage rate
+
+**Grant access if needed:**
+```sql
+GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE <your_role>;
+```
+
+---
+
+## Configuration
+
+Snowglobe loads connection profiles from `~/.snowglobe/config.yaml`. Multiple profiles are supported and selected with `--profile <name>`.
+
+```yaml
+# ~/.snowglobe/config.yaml
+
+default:
+  account: "abc123.us-east-1"
+  user: "jdoe@example.com"
+  role: "ANALYST"
+  warehouse: "ANALYTICS_WH"
+
+  # Auth — choose one:
+  password: "hunter2"                        # password auth
+  # private_key_path: "~/.ssh/snowflake.p8" # key-pair auth
+  # private_key_pwd: "passphrase"           # key passphrase (if encrypted)
+
+  # Optional settings:
+  vim: true                                  # enable vim navigation in the TUI
+  cortex_model: "claude-haiku-4-5"          # Cortex AI model for query optimiser
+
+prod:
+  account: "abc123.us-east-1"
+  user: "admin_user"
+  password: "${SNOWFLAKE_PROD_PASSWORD}"     # environment variables are expanded
+  role: "SYSADMIN"
+  warehouse: "ETL_WH"
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Populate the local SQLite cache from Snowflake
+snowglobe refresh
+
+# 2. Launch the TUI (the default)
+snowglobe
+
+# Or explicitly, with vim-style navigation
+snowglobe tui --vim
+
+# Drop into the REPL shell instead
+snowglobe shell
+
+# Headless commands
+snowglobe access check --user jdoe --object-type TABLE \
+  --object-name MY_DB.PUBLIC.ORDERS --privilege SELECT
+snowglobe cost summary --days 30
+snowglobe optimize query --query-id <query_id>
+snowglobe report full --days 30 --output report.md
+```
+
+---
+
+## Features
+
+### Access explainability
+
+- **Why does X have access?** — Trace every role-inheritance path that grants a user or role a privilege on an object, not just a flat list of grants.
+- **Who can access this?** — Reverse lookup an object: every role and user with access, grouped by privilege, including paths through inherited roles.
+- **Where can this role create things?** — CREATE privilege visibility across account / database / schema scopes with the granting roles called out.
+- **What roles does a user have?** — Direct, excluded, and inherited roles plus the total effective set.
+- **Who has a specific role?** — Direct and inherited members.
+- **Does role X inherit from role Y?** — Every inheritance path between two roles.
+- **What's changed since last refresh?** — Drift detection across grants, role edges, and user assignments.
+
+### Risk & privilege escalation
+
+- **Escalation scan** — Walk every role in the account, find paths to admin roles (ACCOUNTADMIN, SYSADMIN, SECURITYADMIN, USERADMIN, or any role with `MANAGE GRANTS` / DB OWNERSHIP / `IMPORTED PRIVILEGES ON SNOWFLAKE`), and score each path with a composite risk score (target weight × inverse hops × log of user count).
+- **Single-role escalation check** — Pick one role and see exactly which admin targets it can reach and through which chain.
+- **Dormant escalation risks** — Cross-references inactive users (no successful login in 90 days) against risk-bearing roles.
+- **Direct privilege risks** — Roles with dangerous account-level grants that bypass the role graph entirely.
+- **Unused privileges** — Roles with data grants but no recent `QUERY_HISTORY` activity, surfaced for cleanup.
+
+### Cost & query attribution
+
+- **12 cost views** — Account summary, daily trend with rolling average, top expensive queries, per-warehouse, per-user (warehouse + Cortex AI), AI services (Cortex Functions / Analyst / Agent / Code / Snowflake Intelligence), services (pipes / tasks / SPCS / auto-clustering / search optimisation), per-DB storage with monthly cost estimate, replication, materialized-view refresh costs, and Snowflake-native budget status.
+- **Real query attribution** — Uses `QUERY_ATTRIBUTION_HISTORY.CREDITS_ATTRIBUTED_COMPUTE` for per-query credit cost where available; falls back gracefully to `QUERY_HISTORY` with a clear note.
+- **Cortex AI cost tracking** — Each Cortex view is queried individually so accounts without certain features still get partial data rather than a crash.
+- **1-hour TTL local cache** — Cost views are cached in SQLite so repeated visits within the hour are instant; `Re-fetch` forces a fresh Snowflake call.
+- **Drill-downs** — Click a warehouse for its daily trend; click a user for their per-warehouse credit breakdown; click a top query to load it into the Tune screen.
+
+### Query optimiser
+
+- **Eight heuristic detectors** over `GET_QUERY_OPERATOR_STATS` — join explosion, disk spill, pruning failure, cartesian joins, large scans, large window functions, large aggregations, heavy network shuffle.
+- **Snowflake-native insights** from `QUERY_INSIGHTS` (where available).
+- **Operator tree** with per-operator score and time percentage.
+- **Cortex AI suggestions** — opt-in `AI_COMPLETE` call that takes the SQL + heuristic findings + cost attribution and produces a narrative optimisation recommendation. Model is configurable per profile (`cortex_model` in config); defaults to `claude-haiku-4-5`.
+
+### Reports
+
+- **Full report** — cost summary + AI costs + storage + top queries, rendered as markdown via Jinja templates.
+- **Cost-only report** — same shape minus the query section.
+- **User access report** — every effective role and grant for a user, formatted as a markdown audit trail.
+- **CSV exports** — most cost commands accept `--csv <path>` to write directly to a file; the risk scan supports `--csv` and `--json`.
+
+### Local SQLite cache
+
+- All grants, role edges, and user assignments cached locally for instant lookups.
+- **Incremental refresh** — uses `MODIFIED_ON` / `DELETED_ON` watermarks to fetch only changed rows.
+- Cost data uses a 1-hour TTL in the same SQLite store.
+
+---
+
+## The TUI
+
+`snowglobe` (or `snowglobe tui`) opens a full-screen Textual app. Persistent header at the top (profile / role / cache age), nav sidebar on the left, footer with active keybindings at the bottom.
+
+### Screens
+
+Number keys `1`–`7` jump directly:
+
+| # | Screen | What's on it |
+|---|---|---|
+| **1** | **Home** | KPI cards (cache health, connection, this week's spend + risk count), recent expensive queries, hotkeys (`a` access · `w` who-access · `c` cost · `s` risk · `r` refresh) |
+| **2** | **Access** | Seven tabs: Check / Who-access / Create / Roles / Members / Path / Drift. Object-type aware privilege filtering. |
+| **3** | **Risk** | Five tabs: Scan / Escalation / Dormant / Direct grants / Unused. Re-scan + CSV / JSON export. |
+| **4** | **Cost** | All twelve cost views in one place. Window selector (7d / 30d / 90d), Re-fetch button, drill-downs into per-warehouse / per-user / per-service trends. |
+| **5** | **Tune** | Query optimiser. Three-pane: SQL with syntax highlighting; Heuristics / Native insights / Operator tree / Expensive ops / AI on the right. |
+| **6** | **Reports** | Generate Full / Cost-only / User-access reports with live markdown preview + Save. |
+| **7** | **Refresh** | State counts, refresh actions, connection diagnostics, streaming log. |
+
+### Navigation
+
+| Key | Action |
+|---|---|
+| `Tab` / `Shift-Tab` | Cycle focus between widgets |
+| `Enter` | Activate (button press, fire query, open Select dropdown, expand tree node) |
+| `↑` / `↓` | Navigate within lists / tables / dropdowns / trees |
+| `Esc` | Close drill-downs / cancel running workers / blur input (vim mode) |
+| `1`–`7` | Jump to screen by number |
+| `Ctrl-P` | Command palette (switch themes, change profile, etc.) |
+| `q` | Quit |
+
+### Vim mode *(optional)*
+
+Pass `--vim` or set `vim: true` in your profile config:
+
+| Key | Action | Where |
+|---|---|---|
+| `j` / `k` | Cursor down / up | Lists, tables, trees |
+| `g` / `G` | Top / bottom | Same |
+| `h` / `l` | Collapse / expand | Tree nodes |
+| `Ctrl-d` / `Ctrl-u` | Half-page down / up | Any scrollable |
+| `Esc` | Blur the focused input | Lets `j`/`k` navigate again after typing |
+
+Typing into form fields works as expected — Input widgets consume keypresses before vim bindings fire.
+
+### Themes
+
+Two branded themes ship with the app: `snowglobe-dark` (default) and `snowglobe-light`. Open the command palette with **`Ctrl-P`**, type `theme`, and pick any — Textual's built-ins (`nord`, `monokai`, `dracula`, `catppuccin-*`, etc.) are also listed.
+
+---
+
+## The interactive shell
+
+`snowglobe shell` drops you into a REPL with fuzzy tab-completion on usernames, roles, and object FQNs.
+
+| Command | Description |
+|---|---|
+| `check` | Guided wizard — covers all seven access-style checks step by step |
+| `roles <user>` | Direct + inherited roles for a user |
+| `members <role>` | Direct + inherited users for a role |
+| `path <from> <to>` | Inheritance paths between two roles |
+| `escalation <role>` | Can this role reach admin privileges? |
+| `scan` | Full privilege-escalation scan with risk scoring; `--csv` / `--json` export |
+| `cost` | Cost wizard, or use sub-verbs: `cost summary`, `cost warehouses`, `cost users`, `cost ai`, `cost queries`, `cost trend`, `cost storage`, `cost budget`, `cost replication`, `cost mv` |
+| `optimize <query_id>` | Run the optimiser on a specific query |
+| `drift` | Show access changes since last refresh (or `--days N`) |
+| `unused` | Find roles with data privileges but no recent activity |
+| `report <user>` | Markdown access report for a user |
+| `report full` / `report cost` | Cost / AI / storage / top queries report saved to `.md` |
+| `refresh` | Refresh cached state from Snowflake (`--full` for a complete rebuild) |
+| `status` | Current working state + cache age |
+| `debug` | Connection diagnostics |
+| `help` / `?` | List commands |
+| `use role <name>` / `use user <name>` | Set the active role / user for subsequent commands |
+| `access` / `whoaccess` / `create` | Direct shortcuts that skip the wizard |
+| `exit` | Quit |
+
+---
+
+## Headless CLI
+
+For CI, cron, and scripts. Output formats: `--output table|json` plus per-command `--csv <path>`.
+
+| Command | Description |
+|---|---|
+| `snowglobe` | Launch the TUI (falls back to `shell` if Textual isn't installed) |
+| `snowglobe tui [--vim]` | Launch the TUI explicitly |
+| `snowglobe shell` | Launch the REPL shell |
+| `snowglobe refresh [--full]` | Incremental (default) or full state refresh |
+| `snowglobe debug` | Connection diagnostics (eight-step checklist) |
+| `snowglobe access check` | Explain access for a user / role on an object |
+| `snowglobe access create` | Where can a role create objects? |
+| `snowglobe access whoaccess` | Reverse lookup — who can access this object? |
+| `snowglobe cost summary` | Account spend by service type |
+| `snowglobe cost warehouses` | Per-warehouse credit breakdown |
+| `snowglobe cost users` | Complete cost per user (warehouse + Cortex) |
+| `snowglobe cost ai` | AI/ML token costs by service |
+| `snowglobe cost ai-users` | AI costs per user with service split |
+| `snowglobe cost queries` | Top expensive queries by credits or bytes |
+| `snowglobe cost trend` | Daily spend trend with Δ% and rolling 7-day average |
+| `snowglobe cost storage` | Per-DB storage with estimated monthly cost |
+| `snowglobe cost services` | Pipes / serverless tasks / SPCS / clustering / search optimisation |
+| `snowglobe cost budget` | Snowflake-native budget status |
+| `snowglobe cost replication` | Replication credits |
+| `snowglobe cost mv` | Materialized-view refresh credits |
+| `snowglobe optimize query --query-id <id>` | Full query analysis + Cortex AI suggestion |
+| `snowglobe optimize top-queries [--analyze]` | List top expensive queries; optionally analyse each |
+| `snowglobe report full` | Generate the full markdown report |
+| `snowglobe report cost` | Cost-only markdown report |
+| `snowglobe report queries` | Top-queries CSV export |
+
+### Global options
+
+- `--profile <name>` — connection profile (default: `default`)
+- `--role <name>` — override the role from the profile
+- `--output table|json` — output format
+- `--verbose` / `-v` — verbose output
+
+---
+
+## Security
+
+Snowglobe is **read-only by design** — its guiding principle is that it earns trust by never touching production state.
+
+- The Snowflake connection layer actively blocks `CREATE`, `ALTER`, `DROP`, `GRANT`, `REVOKE`, and `TRUNCATE` statements before they reach Snowflake.
+- All metadata is fetched via bulk queries against `SNOWFLAKE.ACCOUNT_USAGE` (and `ORGANIZATION_USAGE.RATE_SHEET_DAILY` if available).
+- All data stays in your environment. No telemetry, no callbacks, no external requests.
+- Credentials are read from the local config file and never logged.
+- Cortex AI calls run inside your Snowflake account via `AI_COMPLETE` — the SQL and operator stats never leave Snowflake.
+
+---
+
+## Limitations
+
+- **`ACCOUNT_USAGE` has up to ~45 minutes of latency** — very recent grant or query changes won't appear until the next refresh.
+- **STREAMLIT, NOTEBOOK, DYNAMIC TABLE, ALERT, TAG, SECRET** grants aren't in `GRANTS_TO_ROLES`; Snowglobe falls back to live `SHOW GRANTS ON` for those types (slower, but works).
+- **Query Attribution** (`QUERY_ATTRIBUTION_HISTORY`) requires Snowflake's Query Attribution feature, which is not available on Standard tier or older accounts. Snowglobe falls back to `QUERY_HISTORY` with a note in the UI.
+- **Cortex AI views** are not available in all Snowflake regions or tiers. Snowglobe queries each view independently and silently skips missing ones.
+
+---
+
+## Contributing
+
+Pull requests and issues are welcome on [GitHub](https://github.com/jcolethornton/snowglobe).
+
+---
+
+## License
+
+Apache-2.0 © 2026 Jaryd Thornton. See `LICENSE` for the full text.