GAT Command Line Interface#

GAT includes a command line interface for running reports against configuration files with overrides.

Example Run#

Runs the system comparison report based on two configuration files, overrides the display name with new names, and applies a filter to consider p61 and p62 as the whole “System”. You can also override the s1 and s2 system files with new paths but keeping the rest of the scenario configuations. This will write the results to the test_output directory.

gat run multi --s1-config=/path/to/reeds_config.yaml --s2-config=/path/to/sienna_config.yaml --s1-name=reeds_2030 --s2-name=sienna_2030 --area-filter="p61,p62" --output-path=test_output

Example Init and Run#

You can also initialize the global configuration for the report using the init command.

gat init multi --s1-config=/path/to/reeds_config.yaml --s2-config=/path/to/sienna_config.yaml --s1-name=reeds_2030 --s2-name=sienna_2030 --area-filter="p61,p62"

You can then run against the report config and override the parameters for –{s1/s2}-{config,path,name}.

gat run multi --report-config=comparison_report_config.yaml

Command Reference#

gat#

Grid Analysis Toolkit (GAT) CLI.

A toolkit for wrangling data for Bulk Grid Dispatch and Transmission Analysis.

Usage

gat [OPTIONS] COMMAND [ARGS]...

Options

--version#: Show the version and exit.

-v, --verbose#: Show info-level logs

--debug#: Show debug-level logs

config#

View or edit GAT configuration.

Usage

gat config [OPTIONS]

Options

--show#: Show current configuration

--path#: Show config file path

--edit#: Open config file in editor

init#

Initialize a Scenario, Report or Extraction configuration file.

Types of configurations:

REPORTS:

system_comparison (Compares the capacity of two systems)
scenario_single (Standard System + Simulation plots)

SCENARIO:

sienna
plexos
reeds

Usage

gat init [OPTIONS] COMMAND [ARGS]...

report#

Initialize a report configuration.

Usage

gat init report [OPTIONS]

Options

--type <report_type>#: Type of report to initialize

plot#

Generate standard plots directly.

Run with no arguments for an interactive plot selector, or specify

a plot name to generate it directly.

Examples:

gat plot                          # interactive selector
gat plot –list                   # list available plots
gat plot monthly-dispatch         # generate monthly dispatch chart
gat plot total-dispatch -b interactive  # plotly backend

Usage

gat plot [OPTIONS] [NAME]

Options

-l, --list#: List available standard plots

-p, --project <project>#: Project ID

-s, --scenario <scenario>#: Scenario ID

-b, --backend <backend>#: Plot backend: static, interactive

--server <server_url>#: GAT server URL for remote data

Arguments

NAME#: Optional argument

project#

Manage GAT projects (v1.0).

Usage

gat project [OPTIONS] COMMAND [ARGS]...

add#

Add an existing project to your projects.

This creates a lightweight reference in your user metadata that points to the project directory.

Examples:

# Add a local project gat project add ./my-project

# Add and set as default gat project add ./my-project –set-default

# Add with custom ID gat project add ./my-project –id my_proj

Usage

gat project add [OPTIONS] PATH

Options

--id <project_id>#: Project ID (defaults to directory name)

--set-default#: Set as default project

Arguments

PATH#: Required argument

init#

Initialize a new GAT project.

Creates the project directory structure with: - gat-project.yaml (project config) - scenarios/ (scenario configs) - palettes/ (visualization palettes) - pipelines/ (reporting pipelines) - notebooks/ (analysis notebooks) - .gitignore - README.md

Examples:

# Initialize in current directory gat project init .

# Initialize in new directory gat project init ./my-project –name “My Analysis”

# Initialize and set as default gat project init ./my-project –set-default

Usage

gat project init [OPTIONS] [PATH]

Options

--name <name>#: Project name (defaults to directory name)

--description <description>#: Project description

--gat-version <gat_version>#: Required GAT version

--no-palettes#: Don’t copy user palettes into project

--no-add#: Don’t add project to user metadata

--set-default#: Set as default project

Arguments

PATH#: Optional argument

list#

List all your projects.

Shows projects from your user metadata directory (~/.config/gat/projects/).

Examples:

gat project list gat project list –verbose

Usage

gat project list [OPTIONS]

Options

-v, --verbose#: Show detailed information

palette#

Manage project palettes.

Usage

gat project palette [OPTIONS] COMMAND [ARGS]...

add#

Generate a palette from a scenario’s system file.

Creates a new palette by reading the system file from a scenario and auto-generating display categories, colors, and classifications based on the generators found in the system.

Examples:

# Generate palette from a scenario gat project palette add renewable_focus base_2035

# With custom description gat project palette add my_palette base_2035 –description “Focus on renewable technologies”

# For specific project gat project palette add my_palette base_2035 –project my_project

# Show detailed summary gat project palette add my_palette base_2035 –print-summary

Usage

gat project palette add [OPTIONS] PALETTE_NAME SCENARIO_ID

Options

--project <project_id>#: Project ID (uses default if not specified)

--description <description>#: Palette description

--print-summary#: Print a summary of the generated palette

Arguments

PALETTE_NAME#: Required argument

SCENARIO_ID#: Required argument

list#

List all palettes in a project.

Examples:

# List palettes in default project gat project palette list

# List palettes in specific project gat project palette list –project my_project

Usage

gat project palette list [OPTIONS]

Options

--project <project_id>#: Project ID (uses default if not specified)

remove#

Remove a palette from a project.

Examples:

# Remove a palette gat project palette remove my_palette

# Remove without confirmation gat project palette remove my_palette –yes

# Remove from specific project gat project palette remove my_palette –project my_project

Usage

gat project palette remove [OPTIONS] PALETTE_NAME

Options

--project <project_id>#: Project ID (uses default if not specified)

-y, --yes#: Skip confirmation prompt

Arguments

PALETTE_NAME#: Required argument

show#

Show details for a specific palette.

Examples:

# Show palette in default project gat project palette show my_palette

# Show palette in specific project gat project palette show my_palette –project my_project

Usage

gat project palette show [OPTIONS] PALETTE_NAME

Options

--project <project_id>#: Project ID (uses default if not specified)

Arguments

PALETTE_NAME#: Required argument

remove#

Remove a project from your projects.

This only removes the reference from your user metadata. The project directory itself is NOT deleted.

Examples:

gat project remove my_project gat project remove my_project –yes

Usage

gat project remove [OPTIONS] PROJECT_ID

Options

-y, --yes#: Skip confirmation

Arguments

PROJECT_ID#: Required argument

scenario#

Manage project scenarios.

Usage

gat project scenario [OPTIONS] COMMAND [ARGS]...

add#

Add a scenario to a project with automatic path resolution.

Creates a YAML scenario configuration file in the project’s scenarios/ directory.

Paths can be relative (to current directory) or absolute. All paths are resolved to absolute filesystem paths for storage.

For Sienna scenarios: - If –simulation-type is specified (e.g., UC, ED, PF), creates a single scenario

for that specific simulation type

If –simulation-type is NOT specified, auto-discovers all simulation types in the file and creates separate scenarios for each (e.g., base_2035_UC, base_2035_ED)

Examples:

# Add a Sienna scenario for a specific simulation type gat project scenario add sienna base_2035 –system ../data/system.json –simulation ../data/results.h5 –simulation-type UC

# Auto-discover all simulation types (creates multiple scenarios) gat project scenario add sienna base_2035 –system ../data/system.json –simulation ../data/results.h5 # This might create: base_2035_UC, base_2035_ED, base_2035_PF

# Add a Sienna scenario with absolute paths gat project scenario add sienna base_2035 –system /full/path/to/system.json –simulation /full/path/to/results.h5 –simulation-type UC

# Add a Sienna scenario with multiple simulation files gat project scenario add sienna multi_week –system ../data/system.json –simulation ../data/week1.h5 –simulation ../data/week2.h5 –simulation-type UC

# Add a Sienna scenario using a glob pattern gat project scenario add sienna weekly –system ../data/system.json –simulation “../data/week*.h5” –simulation-type UC

# Add a ReEDS scenario gat project scenario add reeds reeds_2035 –path ../reeds_output –solve-year 2035

# Add to specific project gat project scenario add sienna test –project my_project –system ../data/system.json –simulation ../data/results.h5 –simulation-type ED

Usage

gat project scenario add [OPTIONS] {sienna|reeds|plexos} SCENARIO_ID

Options

--name <name>#: Scenario name (defaults to scenario_id)

--description <description>#: Scenario description

--project <project_id>#: Project ID (uses default if not specified)

--default-palette <default_palette>#: Default palette to use for this scenario

-y, --yes#: Overwrite existing scenarios without prompting

--system <system>#: [Sienna] Path to system JSON file

--simulation <simulation_paths>#: [Sienna] Path to simulation HDF5 file. Supports: single file, multiple files, or glob patterns (e.g., ‘week*.h5’)

--simulation-type <simulation_type>#: [Sienna] Specific simulation type (UC, ED, PF, etc.). If not specified, auto-discovers all simulations.

--metadata <metadata>#: [Sienna] Path to GAT metadata JSON file

--path <reeds_path>#: [ReEDS] Path to ReEDS output directory

--solve-year <solve_year>#: [ReEDS] Solve year to analyze

--solution <solution>#: [Plexos] Path to Plexos solution file

Arguments

SCENARIO_TYPE#: Required argument

SCENARIO_ID#: Required argument

discover-datasets#

Discover datasets in a scenario and show which will have base_power applied.

By default, datasets with “Power” in their name are flagged for base_power multiplication. Use –save to store these configurations in the scenario YAML.

Examples:

# Discover datasets (preview only) gat project scenario discover-datasets my_scenario_UC

# Discover and save to scenario configuration gat project scenario discover-datasets my_scenario_UC –save

# For specific project gat project scenario discover-datasets my_scenario_UC –project my_project –save

Usage

gat project scenario discover-datasets [OPTIONS] SCENARIO_ID

Options

--project <project_id>#: Project ID (uses default if not specified)

--save#: Save discovered dataset configurations to scenario YAML

Arguments

SCENARIO_ID#: Required argument

list#

List scenarios across all projects or in a specific project.

Examples:

# List scenarios in all projects gat project scenario list

# List scenarios in specific project gat project scenario list my-project

Usage

gat project scenario list [OPTIONS] [PROJECT_ID]

Arguments

PROJECT_ID#: Optional argument

remove#

Remove a scenario from a project.

Examples:

# Remove a scenario gat project scenario remove base_2035

# Remove without confirmation gat project scenario remove base_2035 –yes

# Remove from specific project gat project scenario remove base_2035 –project my_project

Usage

gat project scenario remove [OPTIONS] SCENARIO_ID

Options

--project <project_id>#: Project ID (uses default if not specified)

-y, --yes#: Skip confirmation prompt

Arguments

SCENARIO_ID#: Required argument

show#

Show details for a specific scenario.

Examples:

# Show scenario in default project gat project scenario show base_2035

# Show scenario in specific project gat project scenario show base_2035 –project my_project

Usage

gat project scenario show [OPTIONS] SCENARIO_ID

Options

--project <project_id>#: Project ID (uses default if not specified)

Arguments

SCENARIO_ID#: Required argument

set-default#

Set a project as the default.

The default project is used when no –project option is specified.

Examples:

gat project set-default my_project

Usage

gat project set-default [OPTIONS] PROJECT_ID

Arguments

PROJECT_ID#: Required argument

show#

Show details for a specific project or scenario.

Displays project metadata, scenarios, palettes, and status. Use –verbose to see detailed scenario information. Specify a scenario_id to show details for a specific scenario.

Examples:

# Show project overview gat project show my_project

# Show project with detailed scenario info gat project show my_project –verbose

# Show specific scenario details gat project show my_project base_2035

Usage

gat project show [OPTIONS] PROJECT_ID [SCENARIO_ID]

Options

-v, --verbose#: Show detailed scenario information including paths

Arguments

PROJECT_ID#: Required argument

SCENARIO_ID#: Optional argument

projects#

Manage GAT projects.

Usage

gat projects [OPTIONS] COMMAND [ARGS]...

list#

List all available projects.

Usage

gat projects list [OPTIONS]

Options

--refresh#: Refresh project cache before listing

refresh#

Refresh the project cache by scanning all sources.

Usage

gat projects refresh [OPTIONS]

show#

Show details for a specific project.

Usage

gat projects show [OPTIONS] PROJECT_ID

Arguments

PROJECT_ID#: Required argument

push#

Push a scenario for server-side ingestion.

Usage

gat push [OPTIONS] PROJECT SCENARIO

Options

-h, --handler <handler>#: Required Handler type (sienna, reeds, plexos)

--system <system_path>#: Path to system file

--simulation <simulation_paths>#: Path(s) to simulation files

--server <server_url>#: Server URL

Arguments

PROJECT#: Required argument

SCENARIO#: Required argument

query#

Execute SQL against a remote scenario.

Usage

gat query [OPTIONS] PROJECT SCENARIO SQL

Options

--server <server_url>#: Server URL

--format <output_format>#

Options:: table | csv | json

Arguments

PROJECT#: Required argument

SCENARIO#: Required argument

SQL#: Required argument

run#

Run reports to generate visualizations and analysis.

Available reports are dynamically discovered from the reports package.

Usage

gat run [OPTIONS] COMMAND [ARGS]...

report#

Run a report from a configuration file.

Usage

gat run report [OPTIONS] CONFIG_PATH

Options

-o, --output <output>#: Output directory

Arguments

CONFIG_PATH#: Required argument

scenarios#

List materialized scenarios on the server.

Usage

gat scenarios [OPTIONS]

Options

--server <server_url>#: Server URL

server#

Manage the GAT data server.

Usage

gat server [OPTIONS] COMMAND [ARGS]...

start#

Start the GAT server (foreground).

Usage

gat server start [OPTIONS]

Options

--host <host>#: Bind address (default: 127.0.0.1)

-p, --port <port>#: Listen port (default: 8815)

--db <db_path>#: Path to DuckDB file

--token <token>#: Auth token (or set GAT_SERVER_AUTH_TOKEN)

status#

Check if a GAT server is running.

Usage

gat server status [OPTIONS]

Options

--server <server_url>#: Server URL

sources#

Manage data sources (Sienna, ReEDS, Plexos simulations).

Usage

gat sources [OPTIONS] COMMAND [ARGS]...

add#

Add a new data source.

Usage

gat sources add [OPTIONS] COMMAND [ARGS]...

plexos#

Add a Plexos simulation source.

Example:

gat sources add plexos “Summer Peak” –solution-path ./Model.xml

Usage

gat sources add plexos [OPTIONS] NAME

Options

--solution-path <solution_path>#: Required Path to Plexos solution file or directory

--description <description>#: Description of this source

Arguments

NAME#: Required argument

reeds#

Add a ReEDS simulation source.

Example:

gat sources add reeds “ReEDS 2035” –path ./reeds_outputs –solve-year 2035

Usage

gat sources add reeds [OPTIONS] NAME

Options

--path <path>#: Required Path to ReEDS output directory

--solve-year <solve_year>#: Solve year to filter results

--description <description>#: Description of this source

Arguments

NAME#: Required argument

sienna#

Add a Sienna simulation source.

Examples:

gat sources add sienna “NTP Base” –system-path ./system.json –simulation-path ./results.h5

gat sources add sienna “Multi-file” –system-path ./system.json
–simulation-path ./week1.h5 –simulation-path ./week2.h5

Usage

gat sources add sienna [OPTIONS] NAME

Options

--system-path <system_path>#: Required Path to Sienna system JSON file

--simulation-path <simulation_paths>#: Required Path to simulation HDF5 file(s). Can be specified multiple times.

--description <description>#: Description of this source

Arguments

NAME#: Required argument

list#

List configured data sources.

Usage

gat sources list [OPTIONS]

remove#

Remove a data source.

Usage

gat sources remove [OPTIONS] NAME

Options

-y, --yes#: Skip confirmation prompt

Arguments

NAME#: Required argument

show#

Show details for a specific source.

Usage

gat sources show [OPTIONS] NAME

Arguments

NAME#: Required argument

types#

List available source types and their required arguments.

Usage

gat sources types [OPTIONS]

GAT Command Line Interface

Contents

GAT Command Line Interface#

Example Run#

Example Init and Run#

Command Reference#

gat#

config#

init#

report#

plot#

project#

add#

init#

list#

palette#

add#

list#

remove#

show#

remove#

scenario#

add#

discover-datasets#

list#

remove#

show#

set-default#

show#

projects#

list#

refresh#

show#

push#

query#

run#

report#

scenarios#

server#

start#

status#

sources#

add#

plexos#

reeds#

sienna#

list#

remove#

show#

types#