Back to Details

pm-cli-usage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

pm-cli Usage Guide

pm-cli 使用指南

You are operating 
pm
, a unified CLI for managing tasks across multiple project management tools (Asana, Notion, etc.). Use this guide to run any pm-cli command correctly.
你正在操作
pm
，这是一个用于跨多个项目管理工具（Asana、Notion等）管理任务的统一CLI工具。使用本指南正确运行任何pm-cli命令。

Tool Overview

工具概述

pm
aggregates tasks from multiple PM providers into a single command-line interface. It supports listing, searching, creating, updating, completing, and viewing tasks with cached responses and JSON output for scripting.
npm package: 
@jogi47/pm-cli
(install: 
npm install -g @jogi47/pm-cli
) Supported providers: 
asana
(fully implemented), 
notion
(planned)
pm
将多个项目管理平台的任务聚合到单一命令行界面中。它支持列出、搜索、创建、更新、完成和查看任务，同时提供缓存响应和JSON输出以支持脚本编写。
npm 包： 
@jogi47/pm-cli
（安装命令：
npm install -g @jogi47/pm-cli
） 支持的平台： 
asana
（已完全实现），
notion
（计划中）

Setup

配置步骤

1. Connect a provider

1. 连接平台

bash
pm connect asana    # Prompts for Personal Access Token
pm connect notion   # Prompts for Notion integration token
The command interactively prompts for credentials. You cannot pass tokens as arguments.
bash
pm connect asana    # 提示输入个人访问令牌
pm connect notion   # 提示输入Notion集成令牌
该命令会交互式提示输入凭据。不能将令牌作为参数传递。

2. Set credentials via environment variables (alternative)

2. 通过环境变量设置凭据（替代方式）

bash
export ASANA_TOKEN=<token>
export NOTION_TOKEN=<token>
Environment variables bypass the interactive 
pm connect
flow.
bash
export ASANA_TOKEN=<token>
export NOTION_TOKEN=<token>
环境变量可跳过交互式的
pm connect
流程。

3. Select a workspace (if the provider has multiple)

3. 选择工作区（如果平台有多个工作区）

bash
pm workspace list -s asana
pm workspace switch -s asana    # Interactive workspace picker
bash
pm workspace list -s asana
pm workspace switch -s asana    # 交互式工作区选择器

Task ID Format

任务ID格式

All tasks use the format 
PROVIDER-externalId
:
  • ASANA-1234567890
    — Asana task with external ID 
    1234567890
  • NOTION-abc123def456
    — Notion page with external ID 
    abc123def456
The provider prefix is case-insensitive when parsing (both 
ASANA-123
and 
asana-123
work).
所有任务均使用
PROVIDER-externalId
格式：
  • ASANA-1234567890
    — 外部ID为
    1234567890
    的Asana任务
  • NOTION-abc123def456
    — 外部ID为
    abc123def456
    的Notion页面
解析时平台前缀不区分大小写（
ASANA-123
和
asana-123
均可生效）。

Commands Reference

命令参考

pm connect <provider>

pm connect <provider>

Connect to a project management provider. Prompts for credentials interactively.
ArgumentRequiredValues
provider
Yes
asana
, 
notion
bash
pm connect asana
If already connected, prints current connection info and suggests 
pm disconnect
first.
连接到项目管理平台。交互式提示输入凭据。
参数是否必填可选值
provider
是
asana
, 
notion
bash
pm connect asana
如果已连接，将显示当前连接信息并建议先执行
pm disconnect
。

pm disconnect <provider>

pm disconnect <provider>

Remove stored credentials for a provider.
ArgumentRequiredValues
provider
Yes
asana
, 
notion
bash
pm disconnect asana
移除平台的已存储凭据。
参数是否必填可选值
provider
是
asana
, 
notion
bash
pm disconnect asana

pm providers

pm providers

List all providers and their connection status.
FlagShortDescription
--json
Output as JSON
bash
pm providers
pm providers --json
列出所有平台及其连接状态。
标志缩写描述
--json
以JSON格式输出
bash
pm providers
pm providers --json

pm workspace [action]

pm workspace [action]

List or switch the active workspace for a provider.
ArgumentRequiredDefaultValues
action
No
list
list
, 
switch
FlagShortDefaultDescription
--source
-s
asana
Provider to manage (
asana
, 
notion
)
bash
pm workspace                    # List workspaces (default: asana)
pm workspace list -s asana      # Explicit list
pm workspace switch -s asana    # Interactive workspace picker
列出或切换平台的活跃工作区。
参数是否必填默认值可选值
action
否
list
list
, 
switch
标志缩写默认值描述
--source
-s
asana
要管理的平台（
asana
, 
notion
）
bash
pm workspace                    # 列出工作区（默认：asana）
pm workspace list -s asana      # 显式列出
pm workspace switch -s asana    # 交互式工作区选择器

pm tasks assigned

pm tasks assigned

List tasks assigned to the current user.
FlagShortDefaultDescription
--source
-s
allFilter by provider (
asana
, 
notion
)
--limit
-l
25
Maximum number of tasks
--json
false
Output as JSON
--refresh
-r
false
Bypass cache, fetch fresh data
bash
pm tasks assigned
pm tasks assigned -s asana -l 10
pm tasks assigned --json
pm tasks assigned -r
列出分配给当前用户的任务。
标志缩写默认值描述
--source
-s
all按平台筛选（
asana
, 
notion
）
--limit
-l
25
最大任务数量
--json
false
以JSON格式输出
--refresh
-r
false
绕过缓存，获取最新数据
bash
pm tasks assigned
pm tasks assigned -s asana -l 10
pm tasks assigned --json
pm tasks assigned -r

pm tasks overdue

pm tasks overdue

List tasks that are past their due date.
FlagShortDefaultDescription
--source
-s
allFilter by provider (
asana
, 
notion
)
--limit
-l
25
Maximum number of tasks
--json
false
Output as JSON
--refresh
-r
false
Bypass cache, fetch fresh data
bash
pm tasks overdue
pm tasks overdue -s asana --json
pm tasks overdue -r
列出已逾期的任务。
标志缩写默认值描述
--source
-s
all按平台筛选（
asana
, 
notion
）
--limit
-l
25
最大任务数量
--json
false
以JSON格式输出
--refresh
-r
false
绕过缓存，获取最新数据
bash
pm tasks overdue
pm tasks overdue -s asana --json
pm tasks overdue -r

pm tasks search "<query>"

pm tasks search "<query>"

Search for tasks matching a text query.
ArgumentRequiredDescription
query
YesSearch string (quote if it contains spaces)
FlagShortDefaultDescription
--source
-s
allFilter by provider (
asana
, 
notion
)
--limit
-l
25
Maximum number of tasks
--json
false
Output as JSON
bash
pm tasks search "login bug"
pm tasks search "api" -s asana -l 5
pm tasks search "urgent" --json
Note: 
search
does not have a 
--refresh
flag — it always fetches live results.
搜索匹配文本查询的任务。
参数是否必填描述
query
是搜索字符串（包含空格时请加引号）
标志缩写默认值描述
--source
-s
all按平台筛选（
asana
, 
notion
）
--limit
-l
25
最大任务数量
--json
false
以JSON格式输出
bash
pm tasks search "登录bug"
pm tasks search "api" -s asana -l 5
pm tasks search "紧急" --json
注意：
search
命令没有
--refresh
标志 —— 它始终获取实时结果。

pm tasks show <id>

pm tasks show <id>

Show detailed information for a single task.
ArgumentRequiredDescription
id
YesTask ID in 
PROVIDER-externalId
format
FlagShortDefaultDescription
--json
false
Output as JSON
--open
-o
false
Open the task in the default browser
bash
pm tasks show ASANA-1234567890
pm tasks show ASANA-1234567890 --json
pm tasks show ASANA-1234567890 -o
显示单个任务的详细信息。
参数是否必填描述
id
是格式为
PROVIDER-externalId
的任务ID
标志缩写默认值描述
--json
false
以JSON格式输出
--open
-o
false
在默认浏览器中打开任务
bash
pm tasks show ASANA-1234567890
pm tasks show ASANA-1234567890 --json
pm tasks show ASANA-1234567890 -o

pm tasks create "<title>"

pm tasks create "<title>"

Create a new task in a provider.
ArgumentRequiredDescription
title
YesTask title (quote if it contains spaces)
FlagShortDefaultDescription
--description
-d
Task description
--source
-s
autoTarget provider (
asana
, 
notion
). Required if multiple providers are connected
--project
-p
Project ID to add the task to
--due
Due date (
YYYY-MM-DD
)
--assignee
-a
Assignee email
--json
false
Output as JSON
bash
pm tasks create "Fix login bug"
pm tasks create "Update docs" --source=asana --due=2026-03-01
pm tasks create "Review PR" -d "Check the auth changes" --json
pm tasks create "Design review" -p PROJECT_ID -a user@example.com
If only one provider is connected, 
--source
is inferred automatically.
在平台中创建新任务。
参数是否必填描述
title
是任务标题（包含空格时请加引号）
标志缩写默认值描述
--description
-d
任务描述
--source
-s
auto目标平台（
asana
, 
notion
）。如果连接了多个平台则为必填项
--project
-p
要添加任务的项目ID
--due
截止日期（
YYYY-MM-DD
）
--assignee
-a
负责人邮箱
--json
false
以JSON格式输出
bash
pm tasks create "修复登录bug"
pm tasks create "更新文档" --source=asana --due=2026-03-01
pm tasks create "审核PR" -d "检查认证变更" --json
pm tasks create "设计评审" -p PROJECT_ID -a user@example.com
如果仅连接了一个平台，
--source
会自动推断。

pm tasks update <id>

pm tasks update <id>

Update an existing task. At least one update flag is required.
ArgumentRequiredDescription
id
YesTask ID in 
PROVIDER-externalId
format
FlagShortDefaultDescription
--title
-t
New task title
--description
-d
New task description
--due
New due date (
YYYY-MM-DD
, or 
"none"
to clear)
--status
New status: 
todo
, 
in_progress
, 
done
--json
false
Output as JSON
bash
pm tasks update ASANA-123456 --title "New title"
pm tasks update ASANA-123456 --due 2026-03-15 --status in_progress
pm tasks update ASANA-123456 --due none           # Clear due date
pm tasks update ASANA-123456 -d "Updated notes" --json
更新现有任务。至少需要一个更新标志。
参数是否必填描述
id
是格式为
PROVIDER-externalId
的任务ID
标志缩写默认值描述
--title
-t
新任务标题
--description
-d
新任务描述
--due
新截止日期（
YYYY-MM-DD
，或
"none"
以清除）
--status
新状态：
todo
, 
in_progress
, 
done
--json
false
以JSON格式输出
bash
pm tasks update ASANA-123456 --title "新标题"
pm tasks update ASANA-123456 --due 2026-03-15 --status in_progress
pm tasks update ASANA-123456 --due none           # 清除截止日期
pm tasks update ASANA-123456 -d "更新说明" --json

pm done <id> [id...]

pm done <id> [id...]

Mark one or more tasks as done. Accepts multiple task IDs.
ArgumentRequiredDescription
ids
YesOne or more task IDs (
PROVIDER-externalId
)
FlagShortDefaultDescription
--json
false
Output as JSON
bash
pm done ASANA-123456
pm done ASANA-123456 ASANA-789012    # Complete multiple tasks
pm done ASANA-123456 --json
将一个或多个任务标记为完成。支持多个任务ID。
参数是否必填描述
ids
是一个或多个任务ID（
PROVIDER-externalId
）
标志缩写默认值描述
--json
false
以JSON格式输出
bash
pm done ASANA-123456
pm done ASANA-123456 ASANA-789012    # 批量完成任务
pm done ASANA-123456 --json

pm open <id>

pm open <id>

Open a task in the default browser.
ArgumentRequiredDescription
id
YesTask ID in 
PROVIDER-externalId
format
bash
pm open ASANA-123456
pm open NOTION-abc123
在默认浏览器中打开任务。
参数是否必填描述
id
是格式为
PROVIDER-externalId
的任务ID
bash
pm open ASANA-123456
pm open NOTION-abc123

Output Modes

输出模式

  • Table (default) — Human-readable table rendered in the terminal.
  • JSON (
    --json
    ) — Machine-readable output. Use this when piping to 
    jq
    , scripting, or parsing results programmatically.
  • 表格（默认）—— 终端中渲染的易读表格。
  • JSON（
    --json
    ）—— 机器可读输出。当通过管道传递给
    jq
    、编写脚本或程序化解析结果时使用。

Caching Behavior

缓存行为

  • Responses are cached with a 5-minute TTL.
  • Use 
    --refresh
    / 
    -r
    on 
    tasks assigned
    and 
    tasks overdue
    to bypass the cache and fetch fresh data.
  • tasks search
    always fetches live results (no cache bypass flag needed).
  • tasks show
    fetches directly from the provider.
  • 响应缓存的TTL为5分钟。
  • 在
    tasks assigned
    和
    tasks overdue
    命令中使用
    --refresh
    / 
    -r
    绕过缓存，获取最新数据。
  • tasks search
    始终获取实时结果（无需缓存绕过标志）。
  • tasks show
    直接从平台获取数据。

Unified Task Model

统一任务模型

Every task returned by pm-cli is normalized to this shape:
id            PROVIDER-externalId (e.g. ASANA-1234567890)
externalId    Original provider ID
title         Task title
description   Task description (may contain HTML/markdown)
status        todo | in_progress | done
dueDate       Due date (if set)
assignee      Assignee display name
project       Project or parent container name
tags          Tags/labels array
source        asana | notion
url           Direct link to the task in the provider's UI
priority      low | medium | high | urgent (if available)
createdAt     Creation timestamp
updatedAt     Last modification timestamp
pm-cli返回的每个任务都标准化为以下结构：
id            PROVIDER-externalId（例如 ASANA-1234567890）
externalId    原始平台ID
title         任务标题
description   任务描述（可能包含HTML/Markdown）
status        todo | in_progress | done
dueDate       截止日期（如果已设置）
assignee      负责人显示名称
project       项目或父容器名称
tags          标签/标签数组
source        asana | notion
url           平台UI中任务的直接链接
priority      low | medium | high | urgent（如果可用）
createdAt     创建时间戳
updatedAt     最后修改时间戳

Common Workflows

常见工作流

Check what's overdue

查看逾期任务

bash
pm tasks overdue
bash
pm tasks overdue

Find a specific task by keyword

通过关键词查找特定任务

bash
pm tasks search "deploy pipeline"
bash
pm tasks search "部署流水线"

Create a task with a due date

创建带截止日期的任务

bash
pm tasks create "Fix auth timeout" --due 2026-03-01
bash
pm tasks create "修复认证超时" --due 2026-03-01

Update a task's status

更新任务状态

bash
pm tasks update ASANA-123456 --status in_progress
bash
pm tasks update ASANA-123456 --status in_progress

Mark tasks as done

标记任务为完成

bash
pm done ASANA-123456
pm done ASANA-123456 ASANA-789012    # Batch complete
bash
pm done ASANA-123456
pm done ASANA-123456 ASANA-789012    # 批量完成

Get task details and open in browser

获取任务详情并在浏览器中打开

bash
pm tasks show ASANA-1234567890 -o
pm open ASANA-1234567890             # Shorthand
bash
pm tasks show ASANA-1234567890 -o
pm open ASANA-1234567890             # 简写形式

Get JSON output for scripting

获取JSON输出用于脚本编写

bash
pm tasks assigned --json
pm tasks overdue -s asana --json
bash
pm tasks assigned --json
pm tasks overdue -s asana --json

Force-refresh stale data

强制刷新过期数据

bash
pm tasks assigned -r
pm tasks overdue --refresh
bash
pm tasks assigned -r
pm tasks overdue --refresh

Switch workspace when working across teams

在跨团队工作时切换工作区

bash
pm workspace switch -s asana
bash
pm workspace switch -s asana