glassity is the command-line interface to Glassity, a
FinOps platform for AWS estates. It reads the same whether a person or an agent runs it:
flags in, JSON out, stable exit codes, no prompts on the critical path, and nothing
mutates without an HMAC-bound second round-trip that shows you the exact request first.
$ glassity opp list --stage assessment --min-savings 1000
Tenant: Example Corp (id: acc_demo) | AWS account: 123456789012
ID STAGE POTENTIAL/MO RESOURCES TITLE
opp_7f2a91 assessment $4182.40 37 Idle NAT gateways in eu-west-1
opp_3c8b04 assessment $1290.00 12 Oversized db.r6g fleet in prod
# Reads run straight through. Writes stop and print the plan.
$ glassity opp transition asg_demo123 --target-state execution --comment "rightsizing merged"
Tenant: Example Corp (id: acc_demo) | AWS account: 123456789012
About to perform a mutation. Re-run with --confirm-token=<TOKEN> to execute.
PATCH https://app.glassity.cloud/api/v1/agent/assignments/asg_demo123/transition?account_id=acc_demo
Authorization: token <REDACTED — sk_live_*********** by glassity binary>
{"comment":"rightsizing merged","target_state":"execution"}
Token expires in 1m0s. Cannot be redeemed in less than 1.5s (review window).
Confirm token:
L1VzZXJzL2Rhdmlk...No network call yet: those are the exact bytes phase 2 sends. Values above are examples.
Using Claude Code? The fastest route is the glassity/agent-skills plugin — ready-made skills and workflow commands over this CLI, with guided setup:
claude plugin marketplace add glassity/agent-skills. Details below.
Homebrew (macOS):
brew install glassity/tap/glassityGo:
go install github.com/glassity/cli/cmd/glassity@latestOr grab a release tarball. Linux and darwin builds for amd64 and arm64 ship on the
Releases page with a checksums.txt:
VERSION=1.0.0
OS=darwin # darwin | linux
ARCH=arm64 # arm64 | amd64
BASE=https://github.com/glassity/cli/releases/download/v${VERSION}
curl -fsSLO ${BASE}/glassity_${VERSION}_${OS}_${ARCH}.tar.gz
curl -fsSLO ${BASE}/checksums.txt
shasum -a 256 --ignore-missing --check checksums.txt
tar -xzf glassity_${VERSION}_${OS}_${ARCH}.tar.gz glassity
sudo install -m 0755 glassity /usr/local/bin/glassityWindows builds ship too, minus the glassity fs group: the FUSE library it depends on
has no Windows port. Building from source needs Go 1.26.5 or newer.
The CLI is a client for the Glassity service, so you need an account first. Sign up at app.glassity.cloud.
glassity auth login # prints a URL and a short code
glassity auth whoami # tenant, AWS accounts, scopes
glassity cost summary --start-date 2026-01-01 --end-date 2026-01-31auth login runs an OAuth device flow: open the printed URL in a browser on any
device, sign in, and the credential lands in your OS keychain. Nothing has to launch a
browser on the host, so this works over SSH, in dev containers, and under WSL.
CI runners have no browser and often no keychain. Mint a Personal Access Token in the Glassity UI and pass it through the environment:
export GLASSITY_TOKEN=<pat>
export GLASSITY_ACCOUNT_ID=<account-prefix-id> # from `glassity auth whoami`
export GLASSITY_AWS_ACCOUNT_ID=<aws-account-id> # scopes cost reads
glassity --output json opp listThe token alone is not enough: tenant-scoped commands need GLASSITY_ACCOUNT_ID
(the account_… prefix id, printed by glassity auth whoami and by auth set-token), and cost commands scope to GLASSITY_AWS_ACCOUNT_ID unless
--aws-account-id is passed explicitly.
GLASSITY_TOKEN takes precedence over the keychain, so nothing is written to disk on the
runner. Where a keychain exists, glassity auth set-token stores a PAT persistently.
Anything an agent has to guess about is a bug. The machine-facing surface is a declared contract, stable across releases unless a release note says otherwise.
Streams are separated. stdout carries the result and nothing else; the tenant
banner, warnings, confirm-token plans, and errors go to stderr, so jq never chokes.
Output is explicit. --output json|table|auto; auto becomes JSON whenever stdout
is not a terminal. Pass --output json in tooling so shape never depends on wiring.
Exit codes are declared.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Transport failure, server error, or anything with no more specific mapping |
| 2 | Client misuse: unknown profile, unsafe mountpoint, most coded server rejections |
| 3 | Not authenticated |
| 4 | Insufficient scope |
| 5 | Confirm-token failure |
Errors carry stable codes. Failures are never JSON. Server rejections render as
error: <code>: <message> (http <status>); a refused mutation leads with a grep target:
mutation rejected: stale_state
The assignment already moved past `execution`.
→ Re-read the assignment with `glassity opp show-assignment` before retrying.
Full reference, gaps included: docs/agent-integration.md.
You don't have to teach your agent this binary —
glassity/agent-skills ships ready-made
skills for it: cost summaries, opportunity triage, commitment recommendations, and
slash commands for the full FinOps workflow, each scoped so the agent can only run
glassity where a skill needs it.
claude plugin marketplace add glassity/agent-skills
/plugin install glassity
Ask "what did we spend last month?" and the agent takes it from there — reads run straight through, and any write walks the two-phase confirmation below.
An agent that can run shell commands can, in principle, send any HTTP request. Splitting the decision from the transmission is what makes review possible.
Phase 1 is the plan at the top of this README. No network call is made: the command
canonicalizes the request (upper-cased method, query sorted by key, JSON body with
sorted keys), writes a fresh 32-byte secret to a 0600 file, and signs an HMAC over the
canonical triple. Under --output json that plan arrives on stdout as method, path,
body_canonical, confirm_token, ttl_seconds, min_review_ms, ready for an approval
gate. Phase 2 replays the identical command with the token:
glassity --output json opp transition asg_demo123 \
--target-state execution --comment "rightsizing merged" \
--confirm-token L1VzZXJzL2Rhdmlk...What makes this a guarantee rather than a courtesy:
- The HMAC covers the canonical method, path, and body. Change any of them between phases and phase 2 refuses to send. The secret file is read and unlinked before use, so every token is single-use.
- For PAT profiles the path includes
?account_id=<tenant>, so retargeting the mutation at another tenant invalidates the token instead of silently succeeding. - Tokens live 60 seconds and cannot be redeemed in the first 1.5. Too fast fails
confirm_token_used_too_quickly, too slowconfirm_token_expired; re-run phase 1.
Two-phase applies to opp approve, opp assign, opp pipeline-move, opp transition,
both opp register-*-artifact commands, pr register, and questionnaire submit.
| Group | What it covers |
|---|---|
auth |
login, whoami, set-token, logout |
opp |
list, show, show-assignment; approve, assign, transition, pipeline-move, register-*-artifact (two-phase) |
cost |
summary, by-service, by-subaccount, mom-trends, ec2-usage, rds-usage (read-only) |
rec |
ec2-list, rds-coverage, rds-recommendations (read-only) |
questionnaire |
list, show, submit (two-phase) |
assignments |
status-report (append-only, single phase) |
pr |
register (two-phase) |
governance |
policies (read-only) |
fs |
mount, unmount, status, info, refresh |
profile |
add |
api |
raw request against any agent endpoint the typed commands do not wrap yet |
glassity <command> --help is the authoritative list of flags. fs earns its own note:
it serves a server-built snapshot of your AWS estate over FUSE as a read-only tree at
~/glassity, because ls, grep, and find are tools every agent already knows.
Nothing is written back through it. Setup and troubleshooting in
docs/filesystem-mount.md.
glassity fs mount && grep -rl "t3.2xlarge" ~/glassity && glassity fs unmount- docs/configuration.md — profiles, env vars, state, uninstall.
- docs/agent-integration.md — the machine contract in full.
- docs/filesystem-mount.md —
glassity fsin depth. - CONTRIBUTING.md to build and contribute; SECURITY.md for vulnerability reports, not the issue tracker.
Apache-2.0. Copyright 2026 Glassity. See LICENSE and NOTICE.