Feature/account mapping

[martrost]

cid-cmd map — Account Mapping

The map command creates an account_map Athena view that enriches your AWS account data with custom taxonomy dimensions (business unit, environment, cost center, etc.). These dimensions can then be used in Cloud Intelligence Dashboards for grouping, filtering, and reporting.

How It Works

The command follows a six-phase workflow:

1. Discovery — auto-detects the organization_data table (from AWS Organizations data collection) and the target Athena database
2. Configuration — prompts you to select data sources and define taxonomy dimensions (or reuses a saved configuration)
3. Data Loading — reads organization data from Athena and optionally loads an external file
4. Transformation — applies taxonomy rules to produce the enriched account map
5. Preview — shows a sample of the output and the generated SQL for confirmation
6. Write — creates the Athena views (account_map, account_map_config, and optionally account_map_file_source)

Usage

# Interactive mode (default) — walks you through configuration
cid-cmd map

# Provide a file with additional taxonomy data
cid-cmd map --file accounts.csv

# Legacy mode — simple account_id/account_name mapping from organization_data
cid-cmd map --simple

# Custom output view name
cid-cmd map --view-name my_account_map

Options

Option	Description
--file PATH	Path to a CSV, Excel, or JSON file containing additional taxonomy columns to join by account ID
--simple	Use legacy mode — creates a basic account_map view with just account_id and account_name from the organization_data table
--view-name TEXT	Name of the output Athena view (default: account_map)
-v / --verbose	Increase log verbosity (can be repeated: -vv)
-y / --yes	Auto-confirm all prompts

Taxonomy Dimension Sources

During interactive configuration you choose one or more data sources for your taxonomy dimensions:

Tags from source table

Extracts values from the hierarchytags column in organization_data. Each selected tag key becomes a column in the output view.

Example: if your accounts are tagged with Environment=Production and CostCenter=Engineering, selecting those tag keys produces environment and cost_center columns.

Additional file (--file)

Joins columns from a CSV/Excel/JSON file by account ID. The file must contain an account ID column; all other selected columns become taxonomy dimensions.

Example file (accounts.csv):

account_id,business_unit,team
123456789012,Retail,Frontend
234567890123,Platform,Data

Split account name

Extracts dimensions by splitting the account_name string on a separator character. You specify the separator and the positional index to extract.

Example: for account name aws-retail-prod, splitting by - at index 1 yields retail, and at index 2 yields prod.

Configuration Persistence

The command saves its configuration as an Athena view (<view_name>_config). On subsequent runs it detects the existing config and offers to reuse it, so you don't have to reconfigure every time.

Views Created

View	Purpose
account_map	The main enriched account mapping view used by dashboards
account_map_config	Stores the mapping configuration for reuse
account_map_file_source	(Only when --file is used) Stores the file data as an Athena view for joins

Prerequisites

• An organization_data table in Athena (typically created by the CID data collection CFN stack)
• Athena workgroup with a configured query result location
• Appropriate IAM permissions for Athena and Glue operations

Examples

Create an account map using AWS Organization tags:

cid-cmd map
# → Select "Tags from source table"
# → Pick tag keys like Environment, CostCenter, Team
# → Preview and confirm

Create an account map enriched with data from a spreadsheet:

cid-cmd map --file ~/Downloads/account_taxonomy.xlsx
# → Select "Additional file" and/or "Tags from source table"
# → Pick columns from the file to use as dimensions
# → Preview and confirm

Re-run with saved configuration (no prompts):

cid-cmd map -y

[martrost]

Added the docs/cid-cmd update so the documentation is available as well