Runbooks - Quickstart Guide

---

1. Choose Your Path

Setup	Time	Personas	Jump To
Tier 1: Single Account	2 min	Developer, SRE	Single Account
Tier 2: Multi-Account Landing Zone	5 min	FinOps, Architect	Multi-Account
Tier 3: Enterprise Cross-Validated	15 min	CFO, CTO, Compliance	Enterprise

---

2. Prerequisites

Required (all tiers)

• runbooks v1.3.2+ installed: pip install runbooks
• AWS CLI configured with SSO profiles
• At least one active AWS SSO session

## Verify installation. Expected: runbooks, version 1.3.2 (or higher)
runbooks --version

## Verify AWS access. Expected: JSON with Account, UserId, Arn
aws sts get-caller-identity --profile $AWS_PROFILE

Profile Requirements by Tier

Profile Variable	Purpose	Required By
AWS_PROFILE	Single-account operations	Tier 1
AWS_BILLING_PROFILE	Cost Explorer (billing-readonly)	Tier 2, 3
AWS_MANAGEMENT_PROFILE	AWS Organizations (management-readonly)	Tier 2, 3
AWS_OPERATIONS_PROFILE	Resource discovery (operations-readonly)	Tier 2, 3

---

Tier 1: Single Account (2 min)

Persona: Developer or SRE doing a quick cost and resource check on one account.

pip install runbooks
export AWS_PROFILE="your-profile"

## Confirm version
runbooks --version

## Run the FinOps dashboard for your account
runbooks finops dashboard --profile $AWS_PROFILE

Expected output

runbooks v1.3.2
FinOps Dashboard — Account: $AWS_ACCOUNT_ID (ap-southeast-2)
─────────────────────────────────────────────────
Top Services by Cost (MTD)
  EC2       $1,240.00
  RDS       $  380.00
  S3        $   42.50
─────────────────────────────────────────────────
Total MTD:  $1,662.50

---

Tier 2: Multi-Account Landing Zone (5 min)

Persona: FinOps engineer or cloud architect managing a multi-account AWS Landing Zone.

export AWS_BILLING_PROFILE="billing-readonly"
export AWS_MANAGEMENT_PROFILE="management-readonly"
export AWS_OPERATIONS_PROFILE="operations-readonly"

## FinOps: monthly cost summary exported as JSON and CSV
runbooks finops dashboard \
  --profile $AWS_BILLING_PROFILE \
  --timeframe monthly \
  --export json \
  --export csv

## Inventory: collect EC2, EBS, S3 across the operations account
runbooks inventory collect \
  --profile $AWS_OPERATIONS_PROFILE \
  --resources ec2,ebs,s3 \
  --csv \
  --json

Expected output (finops dashboard)

FinOps Dashboard — Multi-Account (monthly)
─────────────────────────────────────────────────────────────
Account                   MTD Cost    MoM Change
billing-account           $18,420      +3.2%
operations-account        $ 9,110      -1.1%
sandbox-account           $   840      +12%
─────────────────────────────────────────────────────────────
Organisation Total:       $28,370
Exports: finops-dashboard.json, finops-dashboard.csv

Azure support

export AZURE_SUBSCRIPTION_ID="your-subscription-id"
runbooks finops azure monthly

---

Tier 3: Enterprise Cross-Validated (15 min)

Persona: Enterprise architect, CFO, or compliance team requiring MCP-validated results at 99.5% accuracy.

export AWS_BILLING_PROFILE="billing-readonly"
export AWS_OPERATIONS_PROFILE="operations-readonly"

## Step 1: MCP-validated FinOps dashboard (≥99.5% accuracy gate)
runbooks finops dashboard \
  --profile $AWS_BILLING_PROFILE \
  --validation-level mcp \
  --export json

## Step 2: Cross-validate inventory against MCP (EC2, threshold 99.5%)
runbooks inventory validate-mcp \
  --resource-type ec2 \
  --profile $AWS_OPERATIONS_PROFILE \
  --threshold 99.5

## Step 3: Architect-mode activity analysis
runbooks finops dashboard \
  --profile $AWS_BILLING_PROFILE \
  --activity-analysis \
  --mode architect

## Step 4: CFO report (markdown export)
runbooks finops dashboard \
  --mode cfo \
  --export markdown

## Step 5: CTO report (markdown export)
runbooks finops dashboard \
  --mode cto \
  --export markdown

Expected output (MCP validation)

MCP Cross-Validation — EC2 (ap-southeast-2)
─────────────────────────────────────────────────────────────
Native API:   N instances
MCP result:   N instances
Accuracy:     100.0% ✅  (threshold: 99.5%)
─────────────────────────────────────────────────────────────
Validation PASSED. Evidence written to tmp/runbooks/cross-validation/

---

3. Troubleshooting

SSO session expired

Error: Token has expired and refresh failed

Fix: Re-authenticate with AWS SSO.

aws sso login --profile $AWS_PROFILE
## For multi-account setups, login to each profile:
aws sso login --profile $AWS_BILLING_PROFILE
aws sso login --profile $AWS_OPERATIONS_PROFILE

Wrong region — no results

No resources found

Fix: Specify your primary region explicitly.

runbooks finops dashboard --profile $AWS_PROFILE --regions ap-southeast-2

Missing Cost Explorer permissions

Error: AccessDeniedException — ce:GetCostAndUsage

Fix: The billing profile requires ce:GetCostAndUsage and ce:GetCostForecast. Ask your AWS administrator to attach the AWSBillingReadOnlyAccess managed policy to the SSO permission set.

MCP validation fails (SRE mode)

Use --validation-level basic as a fallback until MCP validation is stable in your environment.

runbooks finops dashboard --profile $AWS_BILLING_PROFILE --validation-level basic

---

4. Next Steps

Goal	Reference
Full FinOps command options	FinOps CLI Reference
Full Inventory command options	Inventory CLI Reference
All 122 CLI commands	All Commands
FinOps Dashboard deep-dive	FinOps Dashboard
Getting started guide	CLI Getting Started