pm-cli Usage Guide
You are operating
, 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
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: (install:
npm install -g @jogi47/pm-cli
)
Supported providers: (fully implemented),
(planned)
Setup
1. Connect a provider
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.
2. Set credentials via environment variables (alternative)
bash
export ASANA_TOKEN=<token>
export NOTION_TOKEN=<token>
Environment variables bypass the interactive
flow.
3. Select a workspace (if the provider has multiple)
bash
pm workspace list -s asana
pm workspace switch -s asana # Interactive workspace picker
Task ID Format
All tasks use the format
:
- — Asana task with external ID
- — Notion page with external ID
The provider prefix is
case-insensitive when parsing (both
and
work).
Commands Reference
Connect to a project management provider. Prompts for credentials interactively.
| Argument | Required | Values |
|---|
| Yes | , |
If already connected, prints current connection info and suggests
first.
Remove stored credentials for a provider.
| Argument | Required | Values |
|---|
| Yes | , |
List all providers and their connection status.
| Flag | Short | Description |
|---|
| | Output as JSON |
bash
pm providers
pm providers --json
List or switch the active workspace for a provider.
| Argument | Required | Default | Values |
|---|
| No | | , |
| Flag | Short | Default | Description |
|---|
| | | Provider to manage (, ) |
bash
pm workspace # List workspaces (default: asana)
pm workspace list -s asana # Explicit list
pm workspace switch -s asana # Interactive workspace picker
List tasks assigned to the current user.
| Flag | Short | Default | Description |
|---|
| | all | Filter by provider (, ) |
| | | Maximum number of tasks |
| | | Output as JSON |
| | | Bypass cache, fetch fresh data |
bash
pm tasks assigned
pm tasks assigned -s asana -l 10
pm tasks assigned --json
pm tasks assigned -r
List tasks that are past their due date.
| Flag | Short | Default | Description |
|---|
| | all | Filter by provider (, ) |
| | | Maximum number of tasks |
| | | Output as JSON |
| | | Bypass cache, fetch fresh data |
bash
pm tasks overdue
pm tasks overdue -s asana --json
pm tasks overdue -r
pm tasks search "<query>"
Search for tasks matching a text query.
| Argument | Required | Description |
|---|
| Yes | Search string (quote if it contains spaces) |
| Flag | Short | Default | Description |
|---|
| | all | Filter by provider (, ) |
| | | Maximum number of tasks |
| | | Output as JSON |
bash
pm tasks search "login bug"
pm tasks search "api" -s asana -l 5
pm tasks search "urgent" --json
Note:
does
not have a
flag — it always fetches live results.
Show detailed information for a single task.
| Argument | Required | Description |
|---|
| Yes | Task ID in format |
| Flag | Short | Default | Description |
|---|
| | | Output as JSON |
| | | 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
pm tasks create "<title>"
Create a new task in a provider.
| Argument | Required | Description |
|---|
| Yes | Task title (quote if it contains spaces) |
| Flag | Short | Default | Description |
|---|
| | | Task description |
| | auto | Target provider (, ). Required if multiple providers are connected |
| | | Project ID to add the task to |
| | | Due date () |
| | | Assignee email |
| | | 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,
is inferred automatically.
Update an existing task. At least one update flag is required.
| Argument | Required | Description |
|---|
| Yes | Task ID in format |
| Flag | Short | Default | Description |
|---|
| | | New task title |
| | | New task description |
| | | New due date (, or to clear) |
| | | New status: , , |
| | | 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
Mark one or more tasks as done. Accepts multiple task IDs.
| Argument | Required | Description |
|---|
| Yes | One or more task IDs () |
| Flag | Short | Default | Description |
|---|
| | | Output as JSON |
bash
pm done ASANA-123456
pm done ASANA-123456 ASANA-789012 # Complete multiple tasks
pm done ASANA-123456 --json
Open a task in the default browser.
| Argument | Required | Description |
|---|
| Yes | Task ID in format |
bash
pm open ASANA-123456
pm open NOTION-abc123
Output Modes
- Table (default) — Human-readable table rendered in the terminal.
- JSON () — Machine-readable output. Use this when piping to , scripting, or parsing results programmatically.
Caching Behavior
- Responses are cached with a 5-minute TTL.
- Use / on and to bypass the cache and fetch fresh data.
- always fetches live results (no cache bypass flag needed).
- 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
Check what's overdue
Find a specific task by keyword
bash
pm tasks search "deploy pipeline"
Create a task with a due date
bash
pm tasks create "Fix auth timeout" --due 2026-03-01
Update a task's status
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
Get task details and open in browser
bash
pm tasks show ASANA-1234567890 -o
pm open ASANA-1234567890 # Shorthand
Get JSON output for scripting
bash
pm tasks assigned --json
pm tasks overdue -s asana --json
Force-refresh stale data
bash
pm tasks assigned -r
pm tasks overdue --refresh
Switch workspace when working across teams
bash
pm workspace switch -s asana