Azure PIM CLI (azpim)

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

功能特性

• 🔐 角色激活 - 快速激活符合条件的 Azure PIM 角色
• 🔓 角色停用 - 在不再需要时停用已激活的角色
• 📋 交互式菜单 - 用户友好的菜单驱动界面
• ✨ 美观的用户界面 - 带有旋转动画和色彩的精美终端体验
• 🔄 多角色支持 - 同时激活或停用多个角色
• 📊 状态跟踪 - 激活/停用状态的实时反馈
• 💾 预设 - 保存并重复使用激活/停用配置
• ⭐ 收藏夹 - 将订阅标记为收藏以便快速访问
• 🗃️ 订阅缓存 - 自动缓存订阅（6小时 TTL）以加快启动速度
• 🚀 非交互模式 - 用于脚本和自动化的 CLI 标志
• 🔔 更新通知 - 自动检查更新，行为可配置
• 📤 JSON输出 - 机器可读的输出，便于与其他工具集成
• 👤 按用户数据隔离 - 配置和缓存按 Azure 用户 ID 存储

先决条件

在使用 azpim 之前，请确保您拥有：

1. Node.js (v18 或更高版本)
2. Azure CLI 已安装并配置
3. Azure 帐户 具有 PIM 合格角色

Azure CLI 设置

# 安装 Azure CLI（如果未安装）
# 参见：https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

# 登录 Azure
az login

# 验证登录状态
az account show

安装

全局安装（推荐）

# 使用 npm
npm install -g azpim

# 使用 pnpm
pnpm add -g azpim

# 使用 yarn
yarn global add azpim

安装后，azpim 命令即可全局使用。

从 azp-cli 迁移

如果您之前使用过 azp-cli，您的预设存储在 ~/.config/azp-cli/（或 Windows 上的 %APPDATA%\azp-cli\）中。迁移步骤：

1. 将您的 presets.json 复制到新位置：~/.config/azpim/（或 Windows 上的 %APPDATA%\azpim\）
2. 卸载旧包：npm uninstall -g azp-cli

从源码安装（开发）

# 克隆仓库
git clone https://github.com/tapanmeena/azpim.git
cd azpim

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 为开发创建全局链接
npm link

使用说明

运行 CLI

# 全局安装后
azpim

# 或使用特定命令
azpim activate
azpim deactivate
azpim preset list
azpim update

# 开发模式（从源码）
pnpm dev

命令

命令	别名	描述
activate	a	在 Azure PIM 中激活角色（默认）
deactivate	d	在 Azure PIM 中停用角色
preset	-	管理可重复使用的预设
favorites	fav	管理收藏订阅
check-update	update, upgrade	检查是否有新版本
help	-	显示帮助信息

全局标志：

• --debug - 启用调试日志
• --version - 显示版本号

预设子命令

命令	描述
preset list	列出所有可用的预设
preset show	显示特定预设的详细信息
preset add	添加新预设（交互式向导）
preset edit	编辑现有预设（交互式向导）
preset remove	移除预设

收藏夹子命令

命令	描述
favorites list	列出所有收藏订阅
favorites add	将订阅添加到收藏夹
favorites remove	从收藏夹中移除订阅
favorites clear	清空所有收藏
favorites export	将收藏导出到文件
favorites import	从文件导入收藏
favorites refresh	刷新订阅缓存

更新

您可以检查是否有新版本可用：

azpim update
# 别名
azpim upgrade

注意：

• azpim update 在已是最新时退出代码为 0，有更新时退出代码为 2，出错时退出代码为 1。
• --check-only - 仅检查并打印状态，不显示升级说明。
• --output json 返回适合脚本的结构化响应。
• 默认情况下，azpim activate 和 azpim deactivate 还会每天最多一次显示简短的“有更新可用”提示（仅文本模式）。
• 通过 AZPIM_NO_UPDATE_NOTIFIER=1（或 AZPIM_DISABLE_UPDATE_CHECK=1）禁用更新检查。

更新检查缓存与预设一起存储在配置目录中：

• macOS/Linux：~/.config/azpim/update-check.json（或 $XDG_CONFIG_HOME/azpim/update-check.json）
• Windows：%APPDATA%\azpim\update-check.json

非交互模式（自动化）

使用标志直接激活或停用 PIM 角色，无需通过交互式菜单，非常适合脚本和 CI/CD 工作流程。

激活示例

# 按名称激活单个角色（非交互）
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --duration-hours 2 \
   --justification "紧急应对事件" \
   --output json

# 激活多个角色（重复 --role-name）
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --role-name "User Access Administrator"

# 如果角色名称匹配多个合格角色（不同范围），
# --non-interactive 会报错，除非您明确允许激活所有匹配项
azpim activate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --allow-multiple

# 预览将发生的情况而不提交请求
azpim activate --non-interactive --dry-run \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Contributor" \
   --output json

停用示例

# 停用特定角色
azpim deactivate --non-interactive --yes \
   --subscription-id <SUBSCRIPTION_GUID> \
   --role-name "Owner" \
   --justification "任务完成"

# 跨所有订阅停用（省略 subscription-id）
azpim deactivate --non-interactive --yes \
   --role-name "Contributor" \
   --allow-multiple

可用标志

通用标志（激活/停用）：

• --non-interactive - 禁用交互式提示
• -y, --yes - 跳过确认提示
• --subscription-id <id> - 目标订阅（停用时可选）
• --role-name <name> - 目标角色名称（可重复）
• --allow-multiple - 允许多个角色匹配
• --dry-run - 预览而不提交
• --output <text|json> - 输出格式（默认：text）
• --quiet - 抑制非必要输出

激活专用：

• --duration-hours <n> - 持续时间（1-8 小时，默认值因角色而异）
• --justification <text> - 激活理由

停用专用：

• --justification <text> - 停用理由（可选）

预设

预设让您保存日常的激活/停用例程（订阅 + 角色名称 + 持续时间 + 理由），并通过 --preset <name> 重复使用。

预设文件位置

默认情况下，预设存储在按用户划分的配置文件中：

• macOS/Linux：~/.config/azpim/presets.json（或 $XDG_CONFIG_HOME/azpim/presets.json）
• Windows：%APPDATA%\azpim\presets.json

可通过以下方式覆盖位置：

• AZPIM_PRESETS_PATH=/path/to/presets.json

预设内容

一个预设可以定义一个或两个块：

• activate：subscriptionId、roleNames[]、durationHours、justification、allowMultiple
• deactivate：subscriptionId（可选）、roleNames[]、justification、allowMultiple

justification 支持简单模板：

• ${date} → YYYY-MM-DD
• ${datetime} → ISO 时间戳
• ${userPrincipalName} → 从 Microsoft Graph /me 解析

常用工作流程

# 创建预设（交互式向导）
azpim preset add daily-ops

# 通过 Azure 集成创建预设（获取订阅/角色）
azpim preset add daily-ops --from-azure

# 编辑预设（交互式向导）
azpim preset edit daily-ops

# 列出所有预设
azpim preset list

# 查看单个预设详情
azpim preset show daily-ops

# 移除预设
azpim preset remove daily-ops

# 使用预设（标志仍会覆盖预设值）
azpim activate --preset daily-ops --yes

# 使用预设的非交互运行
azpim activate --preset daily-ops --non-interactive --yes --output json

# 使用预设停用
azpim deactivate --preset daily-ops --non-interactive --yes

默认设置

当您通过 azpim preset add 创建预设时，可以选择将其设置为 activate 和/或 deactivate 的默认预设。

• 当您运行单次流且未显式提供所需标志时，默认预设会自动应用。
• 示例：设置默认激活预设后，azpim activate --non-interactive --yes 无需指定 --subscription-id / --role-name 即可工作。

示例会话

╔════════════════════════════════════════════════════╗
║     Azure PIM CLI - 角色激活管理器                  ║
╚════════════════════════════════════════════════════╝

✔ 身份验证成功

┌─ 用户信息 ──────────────────────────────────────────
│ 姓名：张三
│ 邮箱：[email protected]
└──────────────────────────────────────────────────────

✔ 找到 3 个订阅

? 您想做什么？
❯ ▶ 激活角色
  ◼ 停用角色
  ✕ 退出

角色激活流程

1. 从可用的 Azure 订阅中选择一个
2. 选择一个或多个符合条件的角色进行激活
3. 指定激活持续时间（1-8 小时）
4. 提供激活理由
5. 确认并激活

角色停用流程

1. 查看所有当前已激活的角色（跨订阅）
2. 选择要停用的角色
3. 确认停用

收藏夹

收藏夹允许您标记特定订阅以便快速访问。在交互式菜单中，收藏的订阅会显示在订阅列表的顶部。

收藏夹文件位置

默认情况下，收藏夹按用户存储：

• macOS/Linux：~/.config/azpim/users/<userId>/favorites.json
• Windows：%APPDATA%\azpim\users\<userId>\favorites.json

可通过以下方式覆盖位置：

• AZPIM_FAVORITES_PATH=/path/to/favorites.json

常用工作流程

# 列出所有收藏
azpim favorites list
azpim fav list

# 将订阅添加到收藏夹
azpim favorites add <subscription-id>

# 即使订阅不在缓存中也添加
azpim favorites add <subscription-id> --force

# 从收藏夹中移除订阅
azpim favorites remove <subscription-id>

# 清空所有收藏
azpim favorites clear

# 将收藏导出到文件
azpim favorites export ./my-favorites.json

# 从文件导入收藏（替换现有）
azpim favorites import ./my-favorites.json

# 导入收藏并与现有合并
azpim favorites import ./my-favorites.json --merge

# 刷新订阅缓存
azpim favorites refresh

订阅缓存