Azure PIM CLI (azpim)

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

Terminal UI

功能特性

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

先决条件

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

Node.js (v18 或更高版本)
Azure CLI 已安装并配置
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\）中。迁移步骤：

将您的 presets.json 复制到新位置：~/.config/azpim/（或 Windows 上的 %APPDATA%\azpim\）
卸载旧包：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

命令

全局标志：

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

预设子命令

收藏夹子命令

更新

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

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 个订阅

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

角色激活流程

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

角色停用流程

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

收藏夹

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

收藏夹文件位置

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

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

订阅缓存

azpim 自动缓存订阅信息以改善启动速度。缓存具有 6 小时的 TTL（生存时间），过期时会自动刷新。

缓存位置

缓存文件按用户存储：

macOS/Linux：~/.config/azpim/users/<userId>/subscriptions-cache.json
Windows：%APPDATA%\azpim\users\<userId>\subscriptions-cache.json

刷新缓存

# 强制刷新订阅缓存
azpim favorites refresh

开发

可用脚本

# 以开发模式运行，支持热重载
pnpm dev

# 构建 TypeScript 项目
pnpm build

# 运行已构建的应用
pnpm start

# 检查代码规范
pnpm lint

变更日志与版本发布

本仓库使用 Keep a Changelog 格式，记录在 CHANGELOG.md 中。

发布版本

确保 CHANGELOG.md 中 Unreleased 部分下包含了最新条目。
运行以下命令之一：

# 根据提交自动确定下一个版本，更新 CHANGELOG.md，
# 提升 package.json 版本，并创建 git 标签。
pnpm release

# 预览将要发生的变化
pnpm release:dry

# 如果需要，强制指定特定版本提升
pnpm release -- --release-as patch
pnpm release -- --release-as minor
pnpm release -- --release-as major

推送提交和标签：

git push --follow-tags

发布到 npm（如果需要）：

npm publish
# 或
pnpm publish

项目结构

azpim/
├── src/
│   ├── index.ts                        # CLI 入口和命令定义
│   ├── core/                           # 基础工具（不包含领域逻辑）
│   │   ├── constants.ts                # 共享魔法值和默认值
│   │   ├── errors.ts                   # 统一错误处理工具
│   │   ├── json-store.ts              # 通用 JSON 文件持久化
│   │   ├── paths.ts                    # 配置文件/数据文件路径解析
│   │   └── ui.ts                       # 终端 UI（旋转动画、格式、颜色）
│   ├── azure/                          # Azure SDK 包装器
│   │   ├── auth.ts                     # Azure CLI 凭据 + Graph /me 查询
│   │   └── azure-pim.ts               # PIM 角色激活/停用 API
│   ├── data/                           # 本地数据持久化
│   │   ├── favorites.ts               # 收藏夹管理
│   │   ├── presets.ts                  # 预设配置与验证
│   │   ├── subscription-cache.ts      # 订阅缓存（6小时 TTL）
│   │   └── update-check.ts            # 更新通知系统
│   └── cli/                            # 交互式流程和命令脚手架
│       ├── cli.ts                      # 主菜单循环和共享辅助函数
│       ├── command-handler.ts         # 可复用的命令包装器（认证、UI、错误）
│       ├── activate-flow.ts           # 角色激活（单次运行 + 交互式）
│       ├── deactivate-flow.ts         # 角色停用（单次运行 + 交互式）
│       ├── subscription-selector.ts   # 订阅搜索/选择（含收藏夹）
│       ├── favorites-manager.ts       # 交互式收藏夹管理菜单
│       └── presets-cli.ts             # 预设添加/编辑/管理向导
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

架构

代码遵循分层模块结构：

core/ — 零依赖工具，项目全局共享。json-store.ts 提供了所有数据持久化文件使用的通用加载/保存模式。errors.ts 集中处理错误提取和命令级错误处理。constants.ts 消除了魔法值。
azure/ — 围绕 Azure SDK（@azure/identity、@azure/arm-authorization）的薄包装器，以及通过原生 fetch 调用的轻量级 Microsoft Graph /me 接口。不包含 UI 逻辑。
data/ — 本地文件持久化（收藏夹、预设、订阅缓存、更新状态）。全部使用 json-store 实现一致的文件 I/O。
cli/ — 面向用户的交互式流程和命令脚手架。command-handler.ts 提供了 withCommandHandler 包装器，消除了所有 Commander 命令中的样板代码（认证、UI 设置、错误处理）。激活和停用流程共享中的函数。

技术栈

TypeScript - 类型安全的 JavaScript
Commander.js - CLI 框架
Inquirer.js - 交互式提示
Ora - 优雅的终端旋转动画
Chalk - 终端字符串样式
Azure SDK - Azure 服务集成

环境变量

变量

故障排除

"Azure CLI not found" 错误

请确保 Azure CLI 已安装且在 PATH 中：

az --version

身份验证错误

确保您已登录 Azure CLI：
```
az login
```
验证您的账户具有 PIM 合格角色：
```
az account show
```
检查您在 Azure AD 中是否拥有必要的权限

未找到订阅

确认您的 Azure 账户拥有订阅的访问权限
尝试刷新 Azure CLI 登录：az login --refresh

许可证

本项目采用 ISC 许可证。

作者

Tapan Meena - [email protected]

贡献

欢迎贡献！请随时提交 Pull Request。

Fork 本仓库
创建您的功能分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m '添加某个惊人功能')
推送到分支 (git push origin feature/amazing-feature)
发起 Pull Request

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

`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_PRESETS_PATH`	覆盖预设文件路径
`AZPIM_FAVORITES_PATH`	覆盖收藏夹文件路径
`AZPIM_NO_UPDATE_NOTIFIER`	设为 `1` 可禁用自动更新检查
`AZPIM_DISABLE_UPDATE_CHECK`	`AZPIM_NO_UPDATE_NOTIFIER` 的别名

azpim

最受欢迎

Azure PIM CLI (azpim)

功能特性

先决条件

Azure CLI 设置

安装

全局安装（推荐）

从 azp-cli 迁移

从源码安装（开发）

使用说明

运行 CLI

命令

预设子命令

收藏夹子命令

更新

非交互模式（自动化）

激活示例

停用示例

可用标志

预设

预设文件位置

预设内容

常用工作流程

默认设置

示例会话

角色激活流程

角色停用流程

收藏夹

收藏夹文件位置

常用工作流程

订阅缓存

缓存位置

刷新缓存

开发

可用脚本

变更日志与版本发布

推荐的提交信息

发布版本

项目结构

架构

技术栈

环境变量

故障排除

"Azure CLI not found" 错误

身份验证错误

未找到订阅

许可证

作者

贡献