pm-cli Usage Guide

You are operating pm, a unified CLI for task management across multiple project management providers.

Tool Overview

pm supports:

provider connection and auth
assigned / overdue / search task views
single-task show / open / update
task creation, including Asana project/section placement
comments
complete / delete batch actions
summary and today dashboard views
Asana task thread and attachment inspection
config and cache management
task-based git branch creation

Supported providers:

asana
notion
trello
linear
clickup

Current capability notes:

task thread and task attachment commands are implemented on the Asana path
image download support for thread/attachment commands is implemented on the Asana path
workspace switching is currently useful for Asana
planned but not implemented yet: pm ui, pm bulk update, pm bulk move, pm bulk create --file

Setup

Connect interactively

pm connect asana
pm connect notion
pm connect trello
pm connect linear
pm connect clickup

Environment variable auth

export ASANA_TOKEN=<token>
export NOTION_TOKEN=<token>
export TRELLO_API_KEY=<api-key>
export TRELLO_TOKEN=<token>
export LINEAR_API_KEY=<token>
export CLICKUP_TOKEN=<token>

Notes:

Notion also needs a database ID during pm connect notion
credentials are prompted interactively when using pm connect
pm providers shows connection state and current workspace/user details

Workspace switching

pm workspace
pm workspace list -s asana
pm workspace switch -s asana

Task ID Format

All tasks use PROVIDER-externalId, for example:

ASANA-1234567890
NOTION-abc123def456
LINEAR-ENG-42

The provider prefix is case-insensitive.

Current Command Surface

Implemented commands:

pm connect
pm disconnect
pm providers
pm workspace
pm today
pm summary
pm open
pm branch
pm comment
pm done
pm delete
pm cache stats
pm cache clear
pm config init
pm config path
pm config list
pm config get
pm config set
pm tasks assigned
pm tasks overdue
pm tasks search
pm tasks show
pm tasks thread
pm tasks attachments
pm tasks create
pm tasks update

Not implemented yet:

pm ui
pm bulk update
pm bulk move
pm bulk create --file

Commands Reference

`pm connect <provider>`

Connect to a provider.

Values:

asana
notion
trello
linear
clickup

Example:

pm connect asana

`pm disconnect <provider>`

Disconnect from a provider and clear stored credentials.

Example:

pm disconnect asana

`pm providers`

Show provider connection status.

Flags:

--json

`pm workspace [action]`

List or switch workspaces.

Arguments:

action: list or switch (default: list)

Flags:

--source, -s: asana, notion, trello, linear, clickup

Example:

pm workspace switch -s asana

Task List Commands

`pm tasks assigned`

List tasks assigned to the current user.

Flags:

--source, -s
--limit, -l
--json
--refresh, -r
--status
--priority
--sort
--plain
--ids-only

Example:

pm tasks assigned --status=todo --sort=priority
pm tasks assigned --plain
pm tasks assigned --ids-only

`pm tasks overdue`

List overdue tasks.

Flags:

--source, -s
--limit, -l
--json
--refresh, -r
--status
--priority
--sort
--plain
--ids-only

Example:

pm tasks overdue --sort=due --plain

`pm tasks search "<query>"`

Search for tasks.

Flags:

--source, -s
--limit, -l
--json
--status
--priority
--sort
--plain
--ids-only

Notes:

search does not have a --refresh flag

Example:

pm tasks search "deploy" --sort=due --ids-only

Task Detail Commands

`pm tasks show <id>`

Show one task in detail.

Flags:

--json
--open, -o

`pm open <id>`

Open a task in the default browser.

`pm comment <id> "<message>"`

Add a comment to a task.

Example:

pm comment ASANA-123456 "Deployed to staging"

Thread and Attachment Commands

`pm tasks thread <id>`

Show task conversation history. On Asana, this can include comments, activity entries, and attachment entries.

Flags:

--json
--comments-only, -c
--with-task
--limit, -l
--download-images
--temp-dir
--cleanup

Notes:

--comments-only removes system activity entries but keeps attachment-related comment output
downloaded images are saved under a task-scoped directory in the chosen temp dir

Examples:

pm tasks thread ASANA-1234567890 --comments-only --with-task
pm tasks thread ASANA-1234567890 --download-images --temp-dir /tmp/pm-cli --cleanup
pm tasks thread ASANA-1234567890 --json

`pm tasks attachments <id>`

Show task attachments without the full thread body.

Flags:

--json
--download-images
--temp-dir
--cleanup

Examples:

pm tasks attachments ASANA-1234567890
pm tasks attachments ASANA-1234567890 --download-images --temp-dir /tmp/pm-cli
pm tasks attachments ASANA-1234567890 --json

Create and Update Commands

`pm tasks create <title>`

Create a new task.

Flags:

--description, -d
--title, -t (repeatable; supports multi-create)
--source, -s
--project, -p
--section
--workspace
--difficulty
--field (repeatable)
--refresh
--due
--assignee, -a
--json

Important rules:

if only one provider is connected, --source is inferred
--section requires --project
--difficulty requires --project
--field requires --project
project/section/workspace can be passed by ID or exact case-insensitive name
Asana project/section/workspace resolution can use --refresh to bypass metadata cache

Examples:

pm tasks create "Fix login bug"
pm tasks create "Automated ticket" --source asana --project "Platform Roadmap" --section "Ready"
pm tasks create "Tune dashboard UX" --source asana --project "Platform Roadmap" --section "Ready" --difficulty "S"
pm tasks create "Ship API integration" --source asana --project "Platform Roadmap" --section "Ready" --field "Difficulty=XS" --field "Area=Backend,Analytics"
pm tasks create --source asana --project "Platform Roadmap" --title "Task A" --title "Task B"

`pm tasks update <id>`

Update an existing task. At least one update flag is required.

Flags:

--title, -t
--description, -d
--due
--status
--project, -p
--workspace
--field (repeatable)
--refresh
--json

Examples:

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
pm tasks update ASANA-123456 --project "Platform Roadmap" --field "Difficulty=S"

Batch-Style Top-Level Actions

`pm done <id> [id...]`

Mark one or more tasks done.

`pm delete <id> [id...]`

Delete one or more tasks.

`pm today`

Show overdue, due today, and in-progress tasks in a grouped view.

Flags:

--source, -s
--json

`pm summary`

Show provider connection status and task count summary.

Flags:

--json

Git Helper

`pm branch <id>`

Create a git branch from a task title.

Flags:

--prefix, -p: feat, fix, chore
--checkout, -c
--no-id

Example:

pm branch ASANA-123456 --prefix feat --checkout

Config and Cache

`pm cache stats`

Show cache file path and entry counts.

`pm cache clear`

Clear cache globally or for one provider.

Flags:

--source

`pm config init`

Create a default .pmrc.json in the current project.

Flags:

--force, -f

`pm config list`

List merged config values as JSON.

`pm config get <key>`

Read a config value by dot path.

`pm config set <key> <value>`

Write a project-level config value into .pmrc.json.

`pm config path`

Show user and project config file paths.

Config behavior:

user config lives under ~/.config/pm-cli/config.json
project config lives in .pmrc.json
project config overrides user config on merge

Output Modes

The CLI supports:

default human/table output
--json
--plain
--ids-only

Examples:

pm tasks assigned --json
pm tasks overdue --plain
pm tasks search "deploy" --ids-only

Caching Behavior

cache TTL is about 5 minutes
use --refresh on tasks assigned and tasks overdue to bypass cache
tasks search can return cached results and does not expose --refresh
tasks show fetches directly from the provider path

Normalized Task Model

Every task returned by pm is normalized roughly like this:

id            PROVIDER-externalId
externalId    Original provider ID
title         Task title
description   Task description
status        todo | in_progress | done
dueDate       Due date when present
assignee      Assignee display name
project       Project or parent container name
placement     Structured project/section placement when available
tags          Tag/label array
source        asana | notion | trello | linear | clickup
url           Direct provider URL
priority      low | medium | high | urgent
createdAt     Creation timestamp
updatedAt     Update timestamp

Thread and attachment-related data can also include:

kind          comment | attachment | activity
attachments   Attachment metadata on thread entries
localPath     Downloaded image path when image download is enabled

Common Workflows

Morning dashboard:

pm today
pm summary

Review task thread with attachments:

pm tasks thread ASANA-123456 --comments-only --with-task
pm tasks attachments ASANA-123456 --download-images --temp-dir /tmp/pm-cli

Create directly in an Asana board column:

pm tasks create "Tune lesson plan UX" \
  --source asana \
  --project "Platform Roadmap" \
  --section "Ready" \
  --difficulty "S"

Filter and pipe IDs:

pm tasks assigned --priority=high,urgent --sort=due
pm tasks overdue --ids-only | xargs -I{} pm done {}

Help Commands

Use built-in help when in doubt:

pm --help
pm tasks --help
pm tasks create --help
pm tasks update --help
pm tasks thread --help
pm tasks attachments --help

pm-cli-usage

pm-cli Usage Guide

Tool Overview

Setup

Connect interactively

Environment variable auth

Workspace switching

Task ID Format

Current Command Surface

Commands Reference

pm connect <provider>

pm disconnect <provider>

pm providers

pm workspace [action]

Task List Commands

pm tasks assigned

pm tasks overdue

pm tasks search "<query>"

Task Detail Commands

pm tasks show <id>

pm open <id>

pm comment <id> "<message>"

Thread and Attachment Commands

pm tasks thread <id>

pm tasks attachments <id>

Create and Update Commands

pm tasks create <title>

pm tasks update <id>

Batch-Style Top-Level Actions

pm done <id> [id...]

pm delete <id> [id...]

pm today

pm summary

Git Helper

pm branch <id>

Config and Cache

pm cache stats

pm cache clear

pm config init

pm config list

pm config get <key>

pm config set <key> <value>

pm config path

Output Modes

Caching Behavior

Normalized Task Model

Common Workflows

Help Commands

`pm connect <provider>`

`pm disconnect <provider>`

`pm providers`

`pm workspace [action]`

`pm tasks assigned`

`pm tasks overdue`

`pm tasks search "<query>"`

`pm tasks show <id>`

`pm open <id>`

`pm comment <id> "<message>"`

`pm tasks thread <id>`

`pm tasks attachments <id>`

`pm tasks create <title>`

`pm tasks update <id>`

`pm done <id> [id...]`

`pm delete <id> [id...]`

`pm today`

`pm summary`

`pm branch <id>`

`pm cache stats`

`pm cache clear`

`pm config init`

`pm config list`

`pm config get <key>`

`pm config set <key> <value>`

`pm config path`