@pagopa/dx-cli

DX CLI

📖 Overview

The DX CLI is a command-line tool designed to help developers manage and validate their development setup according to PagoPA's DevEx guidelines. It provides automated checks and validations to ensure repositories follow the established best practices and conventions.

✨ Features

• Repository Validation: Verify repository setup against DevEx guidelines with the doctor command
• Code Migrations: Apply automated migration scripts (codemods) to update code and configurations
• Project Initialization: Bootstrap new monorepo projects with standardized structure
• Command Specification: Export a machine-readable schema of the CLI command surface
• Cost Optimization: Analyze Azure subscriptions to identify unused or underutilized resources
• Project Information: Display comprehensive information about your project setup and tools
• Developer Experience Optimization: Ensure consistent development practices across projects

🚀 Installation

Install the CLI globally using your preferred package manager:

# Using npm
npm install -g @pagopa/dx-cli

# Using yarn
yarn global add @pagopa/dx-cli

# Using pnpm
pnpm add -g @pagopa/dx-cli

From Source (Development)

# Clone the repository
git clone https://github.com/pagopa/dx.git
cd dx

# Install dependencies (using npm)
npm install

# Or using yarn
yarn install

# Or using pnpm
pnpm install

# Build the CLI
npm run build
# Or: yarn build
# Or: pnpm build

# Run the CLI
node ./apps/cli/bin/index.js --help

🔐 Authentication

The CLI requires GitHub authentication for every command except --version and --help. Authenticate using one of the following (checked in this order):

1. The GH_TOKEN environment variable
2. The GITHUB_TOKEN environment variable
3. The GitHub CLI — run gh auth login

If no credential is found, the CLI exits with an error asking you to log in.

Telemetry is emitted only for members of the pagopa GitHub organization; all other users can use the CLI normally with telemetry disabled.

🛠️ Usage

Available Commands

doctor

Verify the repository setup according to the DevEx guidelines.

dx doctor

This command will:

• Check if you're in a valid Git repository
• Validate that required monorepo scripts are present in package.json
• Check that the turbo.json file exists
• Verify that the installed turbo version meets the minimum requirements

Example output:

$ dx doctor
Checking monorepo scripts...
✅ Monorepo scripts are correctly set up

codemod

Manage and apply migration scripts (codemods) to the repository.

# List available codemods
dx codemod list

# Apply a specific codemod by ID
dx codemod apply <id>

This command helps you:

• View all available migration scripts for your repository
• Apply automated code transformations to keep your codebase up to date
• Migrate configurations and code patterns to newer standards

init

Bootstrap a new monorepo project with standardized structure and optional remote repository provisioning.

dx init

This command will:

• Check that required tools (Terraform CLI and Corepack) are installed
• Interactively prompt for repository name, GitHub organization, and description
• Check that the target GitHub repository does not already exist before proceeding
• Generate a monorepo structure following PagoPA DevEx guidelines
• Ask whether the scaffolded workspace should be published to GitHub immediately
• If confirmed, create the remote GitHub repository using Terraform and push the initial codebase

If the specified GitHub repository already exists, the command will fail early with a clear error message, preventing accidental overwrites.

Example usage:

$ dx init
? Name my-monorepo
? GitHub Organization pagopa
? Description My new PagoPA monorepo
? The project is created on my-monorepo. Would you like to publish it to GitHub at pagopa/my-monorepo now? Yes
...

✔ Terraform CLI is installed!
✔ Workspace files created successfully!
✔ GitHub repository created successfully!
✔ Code pushed to GitHub successfully!

Workspace created successfully!
- Name: my-monorepo
- GitHub Repository: https://github.com/pagopa/my-monorepo

[!NOTE] The command will fail early if required tools are missing. If you choose not to publish immediately, the CLI prints the manual Terraform and git steps required to finish the setup later.

spec

Print the full CLI specification as JSON.

dx spec

This command is useful when you want to:

• Discover commands, arguments, and options programmatically
• Build automation or agentic workflows without scraping --help output
• Inspect the current CLI surface in a stable JSON format

Example output:

{
  "name": "dx",
  "specVersion": "1",
  "version": "0.23.2",
  "commands": []
}

info

Display comprehensive information about your project setup and tools.

dx info

This command provides:

• Current project configuration details
• Installed tool versions
• Repository metadata
• Development environment information

savemoney

Analyze Azure subscriptions to identify unused or underutilized resources that could be costing you money.

dx savemoney [options]

Options:

| Option | Alias | Description | Default | | :-------------- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------- | :----------- | | --config | -c | Path to a YAML configuration file. | N/A | | --format | -f | Report format: table, json, detailed-json, or lint. | table | | --days | -d | Metric analysis period in days (overrides config file). | 30 | | --location | -l | Preferred Azure location for resources (overrides config file). | italynorth | | --tags | -t | Filter resources by tags (key=value key2=value2). Only resources matching all specified tags are analyzed (variadic: space-separated). | N/A | | --source | -s | Restrict findings to a specific source: advisor, custom, or all. | all | | --azqr-report | | Path to an AZQR scan --json report to merge as additional findings (overrides azure.azqrReportPath). | N/A |

--verbose / -v is inherited from the root command. See Global Options.

Example usage:

# Analyze with default settings (interactive prompts)
dx savemoney

# Use a configuration file
dx savemoney --config config.yaml

# Output as JSON with verbose logging
dx savemoney --format json --verbose

# Linter-style output for CI pipelines
dx savemoney --config config.yaml --format lint

# Analyze only resources tagged environment=prod
dx savemoney --config config.yaml --tags "environment=prod"

# Analyze with specific timespan
dx savemoney --days 60 --location italynorth

# Merge an AZQR report (run `azqr scan --mask=false --json` first)
dx savemoney --config config.yaml --azqr-report azqr_action_plan.json

Configuration file example (config.yaml):

azure:
  subscriptionIds:
    - subscription-1
    - subscription-2
  preferredLocation: italynorth
  timespanDays: 30
  azqrReportPath: ./azqr_action_plan.json # optional — merge an AZQR scan report
  thresholds: # optional — omit to use built-in defaults
    vm:
      cpuPercent: 5
    appService:
      cpuPercent: 10
      memoryPercent: 20
    storage:
      transactionsPerDay: 50

Analyzed Azure resources:

• Virtual Machines: Deallocated or stopped VMs, low CPU usage
• Managed Disks: Unattached disks
• Network Interfaces: Unattached NICs
• Public IP Addresses: Unassociated static IPs
• Storage Accounts: Low transaction counts
• App Service Plans: Empty plans or oversized tiers
• Private Endpoints: Unused or misconfigured endpoints
• Container Apps: Not running, zero replicas, low resource usage
• Static Web Apps: No traffic or very low usage patterns
• Azure Advisor recommendations: Reserved Instance and Savings Plan opportunities, right-sizing suggestions, and other cost recommendations surfaced directly from Azure Advisor — with estimated monthly savings where available
• AZQR report (optional, via --azqr-report): billable orphans (cost) and free orphaned resources such as empty subnets or unattached NSGs (cleanup candidates) parsed from an azqr scan --json report

[!NOTE] Currently only Azure is supported. Support for additional cloud providers (AWS) is planned for future releases.

Global Options

These options are available on every subcommand:

• --verbose, -v: Enable verbose output. Lowers the log level to debug so that detailed progress information is emitted, and — when a command fails — prints the full error details, including the underlying cause chain and stack trace, instead of only the top-level message. Defaults to false.
• --version, -V: Display version number
• --help, -h: Display help information

Example:

# Re-run a failing command with full diagnostics
dx --verbose init project

🧪 Development

Run the CLI test suite from the repository root with:

pnpm nx test @pagopa/dx-cli

Some integration tests assert generated file contents with Vitest snapshots. When a generator change intentionally updates those files, refresh the snapshots with:

pnpm nx test @pagopa/dx-cli -- --update

Review the updated __snapshots__ files before committing them.

Made with ❤️ by the PagoPA DevEx Team