Azure PIM CLI (azpim)

A command-line interface tool for managing Azure Privileged Identity Management (PIM) role activations directly from your terminal.

Features

• 🔐 Role Activation - Quickly activate eligible Azure PIM roles
• 🔓 Role Deactivation - Deactivate active roles when no longer needed
• 📋 Interactive Menu - User-friendly menu-driven interface
• ✨ Beautiful UI - Polished terminal experience with spinners and colors
• 🔄 Multi-role Support - Activate or deactivate multiple roles at once
• 📊 Status Tracking - Real-time feedback on activation/deactivation status
• 💾 Presets - Save and reuse activation/deactivation configurations
• ⭐ Favorites - Mark subscriptions as favorites for quick access
• 🗃️ Subscription Cache - Automatic caching of subscriptions (6-hour TTL) for faster startup
• 🚀 Non-interactive Mode - CLI flags for scripting and automation
• 🔔 Update Notifications - Automatic update checks with configurable behavior
• 📤 JSON Output - Machine-readable output for integration with other tools
• 👤 Per-user Data Isolation - Configuration and cache stored per Azure user ID

Prerequisites

Before using azpim, ensure you have:

1. Node.js (v18 or higher)
2. Azure CLI installed and configured
3. Azure account with PIM-eligible roles

Azure CLI Setup

# Install Azure CLI (if not installed)
# See: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

# Login to Azure
az login

# Verify you're logged in
az account show

Installation

Global Installation (Recommended)

# Using npm
npm install -g azpim

# Using pnpm
pnpm add -g azpim

# Using yarn
yarn global add azpim

After installation, the azpim command will be available globally.

Migrating from azp-cli

If you previously used azp-cli, your presets are stored in ~/.config/azp-cli/ (or %APPDATA%\azp-cli\ on Windows). To migrate:

1. Copy your presets.json to the new location: ~/.config/azpim/ (or %APPDATA%\azpim\)
2. Uninstall the old package: npm uninstall -g azp-cli

From Source (Development)

# Clone the repository
git clone https://github.com/tapanmeena/azpim.git
cd azpim

# Install dependencies
pnpm install

# Build the project
pnpm build

# Link globally for development
npm link

Usage

Running the CLI

# After global installation
azpim

# Or with specific commands
azpim activate
azpim deactivate
azpim preset list
azpim update

# Development mode (from source)
pnpm dev

Commands

Command	Alias	Description
activate	a	Activate a role in Azure PIM (default)
deactivate	d	Deactivate a role in Azure PIM
preset	-	Manage reusable presets
favorites	fav	Manage favorite subscriptions
check-update	update, upgrade	Check for a newer version
help	-	Display help information

Global Flags:

• --debug - Enable debug logging
• --version - Show version number

Preset Subcommands

Command	Description
preset list	List all available presets
preset show	Show details of a specific preset
preset add	Add a new preset (interactive wizard)
preset edit	Edit an existing preset (interactive wizard)
preset remove	Remove a preset

Favorites Subcommands

Command	Description
favorites list	List all favorite subscriptions
favorites add	Add a subscription to favorites
favorites remove	Remove a subscription from favorites
favorites clear	Clear all favorites
favorites export	Export favorites to a file
favorites import	Import favorites from a file
favorites refresh	Refresh the subscription cache

Updates

You can check if a newer version is available:

azpim update
# alias
azpim upgrade

Notes:

• azpim update exits with code 0 when up-to-date, 2 when an update is available, and 1 on error.
• --check-only - Only check and print status without showing upgrade instructions.
• --output json returns a structured response suitable for scripts.
• By default, azpim activate and azpim deactivate will also show a short "update available" hint (text mode only) at most once per day.
• Disable update checks via AZPIM_NO_UPDATE_NOTIFIER=1 (or AZPIM_DISABLE_UPDATE_CHECK=1).

The update-check cache is stored alongside presets in your config directory:

• macOS/Linux: ~/.config/azpim/update-check.json (or $XDG_CONFIG_HOME/azpim/update-check.json)
• Windows: %APPDATA%\azpim\update-check.json

Non-interactive Mode (Automation)

Use flags to activate or deactivate PIM roles directly without going through the interactive menu, perfect for scripting and CI/CD workflows.

Activation Examples

# Activate a single role by name (non-interactive)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --duration-hours 2 \
   --justification "Break-glass for incident" \
   --output json

# Activate multiple roles (repeat --role-name)
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --role-name "User Access Administrator"

# If a role name matches multiple eligible roles (different scopes),
# --non-interactive will error unless you explicitly allow activating all matches
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --allow-multiple

# Preview what would happen without submitting requests
azpim activate --non-interactive --dry-run \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --output json

Deactivation Examples

# Deactivate specific roles
azpim deactivate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --justification "Task completed"

# Deactivate across all subscriptions (omit subscription-id)
azpim deactivate --non-interactive --yes \
   --role-name "Contributor" \
   --allow-multiple

Available Flags

Common flags (activate/deactivate):

• --non-interactive - Disable interactive prompts
• -y, --yes - Skip confirmation prompts
• --subscription-id <id> - Target subscription (optional for deactivate)
• --role-name <name> - Role name(s) to target (can be repeated)
• --allow-multiple - Allow multiple role matches
• --dry-run - Preview without submitting
• --output <text|json> - Output format (default: text)
• --quiet - Suppress non-essential output

Activation-specific:

• --duration-hours <n> - Duration (1-8 hours, default varies by role)
• --justification <text> - Justification for activation

Deactivation-specific: