Skip to content

Dual-Mode Invocation Matrix

Choose your mode: CLI mode is the standard for ad-hoc ops tasks and scripting. Jupyter mode is for exploratory analysis, visualisation, and sharing results with stakeholders. Both modes call the same underlying runbooks library — output is identical.

Mode Comparison

Dimension CLI Mode Jupyter / SDK Mode
Invocation uv run runbooks inventory <subcommand> from runbooks.inventory import inventory_modules
Best for Automation, CI pipelines, ad-hoc ops Analysis, visualisation, stakeholder notebooks
Output Rich terminal table + JSON file DataFrame, Plotly charts, Markdown cells
Profile handling --profile $AWS_MANAGEMENT_PROFILE CLI flag boto3.Session(profile_name=os.environ['AWS_MANAGEMENT_PROFILE'])
Pagination Handled internally by Click command Handled by inventory_modules.* functions
HITL review --output-dir writes JSON; HITL reviews file Notebook cell output; HITL reviews rendered notebook

Which mode should I use?

  • CLI: When you need reproducible evidence files (git-tracked) or CI/CD integration
  • Jupyter: When you're exploring data interactively or presenting to stakeholders
  • Both: CLI for evidence capture, Jupyter for executive presentation

Decision Matrix: Which Mode to Use

Task Use CLI Use Jupyter
Daily org account audit ✓
Evidence capture for CMDB import ✓
Automated CI/CD pipeline step ✓
4-way cross-validation (≥99.5%) ✓
Stakeholder analysis with charts ✓
SCP policy impact modelling ✓
Ad-hoc exploration of new API ✓
Jupyter-first discovery sprint ✓

Invocation Mode Comparison

Best for: Automated pipelines, CI/CD, HITL one-shots, git-tracked evidence

export AWS_MANAGEMENT_PROFILE=<your-management-profile>
export AWS_OPERATIONS_PROFILE=<your-operations-profile>
export AWS_DEFAULT_REGION=<your-aws-region>

# Enabled services
runbooks inventory list-enabled-services \
  --profile $AWS_MANAGEMENT_PROFILE \
  --output-dir ./tenants/b2b-energy/raw/organizations/

# Delegated administrators
runbooks inventory list-delegated-administrators \
  --profile $AWS_MANAGEMENT_PROFILE \
  --output-dir ./tenants/b2b-energy/raw/organizations/

# All 4 policy types
runbooks inventory list-org-policies \
  --profile $AWS_MANAGEMENT_PROFILE \
  --policy-type ALL \
  --output-dir ./tenants/b2b-energy/raw/organizations/

# Resource groups (operations account — account-scoped)
runbooks inventory list-resource-groups \
  --profile $AWS_OPERATIONS_PROFILE \
  --region $AWS_DEFAULT_REGION \
  --output-dir ./tenants/b2b-energy/raw/organizations/

Best for: Interactive exploration, data science, CxO demos, stakeholder notebooks

import os
import boto3
from runbooks.inventory import inventory_modules

# Load profiles from env vars (never hardcode)
mgmt_session = boto3.Session(
    profile_name=os.environ["AWS_MANAGEMENT_PROFILE"]
)
ops_session = boto3.Session(
    profile_name=os.environ["AWS_OPERATIONS_PROFILE"]
)

# Pre-flight: confirm management account
sts = mgmt_session.client("sts")
identity = sts.get_caller_identity()
print(f"Management account: {identity['Account']}")

# Enabled services (wraps organizations.list_aws_service_access_for_organization)
enabled_services = inventory_modules.list_aws_service_access_for_organization(
    mgmt_session
)
print(f"Enabled services: {len(enabled_services.get('EnabledServicePrincipals', []))}")

# Organization accounts
accounts = inventory_modules.get_org_accounts(mgmt_session)
print(f"Total accounts: {len(accounts)}")

CLI Mode — Multi-Account LZ Commands

Organizations discovery (management account)

export AWS_MANAGEMENT_PROFILE=<your-management-profile>

# Enabled AWS services across the organization
uv run runbooks inventory list-enabled-services \
    --profile $AWS_MANAGEMENT_PROFILE \
    --output-dir tenants/b2b-energy/raw/organizations/

# Delegated administrator accounts
uv run runbooks inventory list-delegated-administrators \
    --profile $AWS_MANAGEMENT_PROFILE \
    --output-dir tenants/b2b-energy/raw/organizations/

# All organization policies (SCP + Tag + Backup + AI Services)
uv run runbooks inventory list-org-policies \
    --profile $AWS_MANAGEMENT_PROFILE \
    --policy-type ALL \
    --output-dir tenants/b2b-energy/raw/organizations/

# Resource Groups (operations account — account-scoped)
uv run runbooks inventory list-resource-groups \
    --profile $AWS_OPERATIONS_PROFILE \
    --region $AWS_DEFAULT_REGION \
    --output-dir tenants/b2b-energy/raw/organizations/

Existing multi-account commands (already available)

# All org accounts
uv run runbooks inventory list-org-accounts \
    --profile $AWS_MANAGEMENT_PROFILE \
    --format json \
    --output tenants/b2b-energy/raw/organizations/organization-accounts

# Landing Zone readiness check
uv run runbooks inventory check-landingzone \
    --profile $AWS_MANAGEMENT_PROFILE

# Control Tower readiness check
uv run runbooks inventory check-controltower \
    --profile $AWS_MANAGEMENT_PROFILE

# Full 5-layer multi-account pipeline
uv run runbooks inventory workflow-multi-account

Jupyter / SDK Mode

Session setup

import os
import boto3
from runbooks.inventory import inventory_modules

# Load profiles from env vars (never hardcode)
mgmt_session = boto3.Session(
    profile_name=os.environ["AWS_MANAGEMENT_PROFILE"]
)
ops_session = boto3.Session(
    profile_name=os.environ["AWS_OPERATIONS_PROFILE"]
)

# Pre-flight: confirm management account
sts = mgmt_session.client("sts")
identity = sts.get_caller_identity()
print(f"Management account: {identity['Account']}")

Organizations discovery (SDK)

# Enabled services (wraps organizations.list_aws_service_access_for_organization)
enabled_services = inventory_modules.list_aws_service_access_for_organization(
    mgmt_session
)
print(f"Enabled services: {len(enabled_services.get('EnabledServicePrincipals', []))}")

# Organization accounts
accounts = inventory_modules.get_org_accounts(mgmt_session)
print(f"Total accounts: {len(accounts)}")

Output to DataFrame

import pandas as pd

df_accounts = pd.DataFrame(accounts)
df_accounts[["Id", "Name", "Status", "Email"]].head(10)

Output File Convention

CLI mode writes JSON files to --output-dir. Naming convention:

Command Output File
list-enabled-services enabled-services.json
list-delegated-administrators delegated-administrators.json
list-org-policies --policy-type ALL scp-policies.json, tag-policies.json, backup-policies.json, chatbot-policies.json
list-resource-groups resource-groups.json

These filenames are used by the 4-way cross-validation pipeline. Do not rename them.