pm-cli Usage Guide

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.

Tool Overview

pm aggregates tasks from multiple PM providers into a single command-line interface. It supports listing, searching, creating, updating, completing, deleting, and viewing tasks with cached responses, JSON output for scripting, plus cache/config management commands.

npm package: @jogi47/pm-cli (install: npm install -g @jogi47/pm-cli) Supported providers: asana (fully implemented), notion (fully implemented)

Setup

1. Connect a provider

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.

2. Set credentials via environment variables (alternative)

export ASANA_TOKEN=<token>
# Optional token override for Notion:
export NOTION_TOKEN=<token>

Environment variables can supply provider tokens. For Notion, a databaseId is also required and is typically captured via pm connect notion.

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

pm workspace list -s asana
pm workspace switch -s asana    # Interactive workspace picker

Task ID Format

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).

Commands Reference

pm connect <provider>

Connect to a project management provider. Prompts for credentials interactively.

pm connect asana

If already connected, prints current connection info and suggests pm disconnect first.

pm disconnect <provider>

Remove stored credentials for a provider.

pm disconnect asana

pm providers

List all providers and their connection status.

pm providers
pm providers --json

pm workspace [action]

List or switch the active workspace for a provider.

pm workspace                    # List workspaces (default: asana)
pm workspace list -s asana      # Explicit list
pm workspace switch -s asana    # Interactive workspace picker

pm tasks assigned

List tasks assigned to the current user.

pm tasks assigned
pm tasks assigned -s asana -l 10
pm tasks assigned --json
pm tasks assigned -r
pm tasks assigned --status=todo --sort=priority
pm tasks assigned --plain
pm tasks assigned --ids-only

pm tasks overdue

List tasks that are past their due date.

pm tasks overdue
pm tasks overdue -s asana --json
pm tasks overdue -r
pm tasks overdue --sort=due --plain

pm tasks search "<query>"

Search for tasks matching a text query.

pm tasks search "login bug"
pm tasks search "api" -s asana -l 5
pm tasks search "urgent" --json
pm tasks search "deploy" --sort=due --ids-only

Note: search does not have a --refresh flag. Results may be served from cache.

pm tasks show <id>

Show detailed information for a single task.

pm tasks show ASANA-1234567890
pm tasks show ASANA-1234567890 --json
pm tasks show ASANA-1234567890 -o

pm tasks create "<title>"

Create a new task in a provider.

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
pm tasks create "Automated ticket" --source=asana --project "Teacher Feature Development" --section "Prioritised"
pm tasks create "Tune lesson plan UX" --source=asana --project "Teacher Feature Development" --section "Prioritised" --difficulty "S"
pm tasks create "Cover flow API integration" --source=asana --project "Teacher Feature Development" --section "Prioritised" --field "Difficulty=XS" --field "Department=Frontend" --field "Other=Bugs,Analytics"

If only one provider is connected, --source is inferred automatically.

Create command rules:

• --section requires --project.
• --difficulty requires --project.
• --field requires --project.
• Name resolution for Asana project/section/workspace is exact and case-insensitive.
• Use --refresh if cached project/section/custom-field metadata is stale.

pm tasks update <id>

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

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 --field "Importance=High" --field "Teacher Feature Release=PR4"
pm tasks update ASANA-123456 --project "Teacher Feature Development" --field "Other="
pm tasks update ASANA-123456 -d "Updated notes" --json

pm delete <id> [id...]

Delete one or more tasks. Accepts multiple task IDs.

pm delete ASANA-123456
pm delete ASANA-123456 ASANA-789012   # Delete multiple tasks
pm delete ASANA-123456 --json

pm done <id> [id...]

Mark one or more tasks as done. Accepts multiple task IDs.

pm done ASANA-123456
pm done ASANA-123456 ASANA-789012    # Complete multiple tasks
pm done ASANA-123456 --json

pm open <id>

Open a task in the default browser.

pm open ASANA-123456
pm open NOTION-abc123

pm today

Morning dashboard — shows overdue, due today, and in-progress tasks in a grouped view.

pm today
pm today --source=asana
pm today --json

pm summary

Show provider connection status and task count statistics (overdue, due today, in progress, total).

pm summary
pm summary --json

pm cache stats

Show cache file location and entry counts.

pm cache stats

pm cache clear

Clear cache entries globally or for a single provider.

pm cache clear
pm cache clear --source=asana

pm config init

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

pm config init
pm config init --force

pm config list

List merged configuration values from user and project config.

pm config list

pm config get <key>

Read a merged config value by dot-notation key.

pm config get defaultSource
pm config get notion.propertyMap.status

pm config set <key> <value>

Set a project-level config value in .pmrc.json.

pm config set defaultLimit 10
pm config set aliases.today "tasks assigned --status=in_progress"
pm config set notion.propertyMap.status "Status"

pm config path

Show project and user configuration file locations.

pm config path

pm branch <id>

Create a git branch named after a task. Fetches the task title and slugifies it into a branch name.

pm branch ASANA-123456 --prefix feat
pm branch ASANA-123456 --prefix fix --checkout
pm branch NOTION-abc123 --no-id

Branch name format: prefix/PROVIDER-externalId-slugified-title (or prefix/slugified-title with --no-id).

pm comment <id> "<message>"

Add a comment to a task.

pm comment ASANA-123456 "Fixed in commit abc"
pm comment NOTION-abc123 "Needs review"

Help Commands

Use built-in help for command syntax and the latest flags:

pm --help
pm tasks --help
pm tasks create --help
pm tasks update --help

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.
• Plain (--plain) — Tab-separated output, no colors or borders. Useful for piping to awk, cut, etc.
• IDs only (--ids-only) — One task ID per line. Useful for scripting loops (e.g., pm tasks overdue --ids-only | xargs -I{} pm done {}).

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 responses are cached; there is currently no --refresh flag on the command.
• tasks show fetches directly from the provider.

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

Common Workflows

Morning standup check

pm today
pm summary

Check what’s overdue

pm tasks overdue

Find a specific task by keyword

pm tasks search "deploy pipeline"

Create a task with a due date

pm tasks create "Fix auth timeout" --due 2026-03-01

Create directly in a board column with difficulty (Asana)

pm tasks create "Tune lesson plan UX" \
  --source asana \
  --project "Teacher Feature Development" \
  --section "Prioritised" \
  --difficulty "S"

Update a task’s status

pm tasks update ASANA-123456 --status in_progress

Mark tasks as done

pm done ASANA-123456
pm done ASANA-123456 ASANA-789012    # Batch complete

Get task details and open in browser

pm tasks show ASANA-1234567890 -o
pm open ASANA-1234567890             # Shorthand

Get JSON output for scripting

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

Force-refresh stale data

pm tasks assigned -r
pm tasks overdue --refresh

Create a branch from a task and start working

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

Add a comment to a task

pm comment ASANA-123456 "Deployed to staging"

Filter high-priority tasks and sort by due date

pm tasks assigned --priority=high,urgent --sort=due

Pipe task IDs for batch operations

pm tasks overdue --ids-only | xargs -I{} pm done {}

Switch workspace when working across teams

pm workspace switch -s asana