p3-cli

TaskP3 command line interface.

Designed to be friendly to human users and LLMs: commands print concise human-readable output by default, and support --json for full machine-readable output.

Install

Homebrew

brew tap raidon-inc/tap
brew install p3

npm

npm install -g @taskp3/cli

Install (workspace)

cd packages/p3-cli
npm install
npm run build

Quickstart

p3                    # no args: open interactive menu (TTY only)
p3 login --google     # sign in with Google (opens browser)
p3 auth whoami        # show authenticated user
p3 select             # pick an assigned task, set as current, optional branch create/checkout
p3 open               # open the selected task in the browser
p3 next               # show your highest-priority active assigned task
p3 current            # show the current task for this repo
p3 project select     # choose default project for this repo
p3 task create "Task name"   # create a task (prompts to set as current when interactive)
p3 task select        # same as p3 select
p3 project current    # show the current project for this repo
p3 task current       # same as p3 current
p3 task update <taskId> --status "Working on it"   # update task status
p3 current            # show current task
p3 done               # mark the current task Done (or pick one), then optionally checkout development

On first create/listen without --project-id, the CLI selects (or prompts for) your project and saves it as your local default.

Running p3 with no subcommand in an interactive terminal opens a menu for common actions like creating tasks, creating many tasks, listing tasks, and checking auth status.

Authentication

Email + password

p3 login --email [email protected]

Google sign-in

p3 login --google

The CLI prints a browser URL. Complete Google sign-in, then return to the terminal and press Enter. The CLI will finalize auth and prompt for a user if the credential has multiple users.

Check status / logout

p3 auth status
p3 auth logout

Task Commands

With --json, typical fields include task, tasks, total, page, and limit depending on the route.

Interactive Select

p3 select
p3 list
p3 task select

In an interactive terminal, p3 select shows your assigned tasks, lets you pick one, stores it as the current task for the repo, then can:

• create or checkout the task branch
• move the task to Working on it
• copy the task definition to your clipboard

If this repo has no current project configured yet, the CLI first prompts you to select a project and saves it for the repo.

By default, p3 select only shows tasks in Not Started or Working on it. Optional flags:

p3 select --all-statuses
p3 select --include-stuck --include-in-review
p3 select --include-done --include-cancelled

Branch behavior:

• Not Started: create or checkout the task branch, then move the task to Working on it
• Working on it: switch to the local branch if it exists, otherwise create a local tracking branch from remote if it exists there, otherwise offer to create it locally

Branch format:

first-name/feature-slug-task-slug-taskid8

Example:

ryan/app-add-loading-state-2a16151

List

p3 task list --limit 25 --page 1
p3 task list --feature-id <featureId>

Get

p3 task get <taskId>

Search

p3 task search --term "billing"

Create

p3 task create accepts the task name either as positional text or with --name. If you omit both --feature-id and --project-id, the CLI uses the repo's saved default project or prompts you to choose one.

p3 task create "Improve onboarding"
p3 task create "Assign me" --assignTo @hazel --description "..."
p3 task create --name "Improve onboarding" --project-id <projectId>
p3 task create --feature-id <featureId> --name "Improve onboarding"
p3 task create --feature-id <featureId> --name "Fix bug" --description "..."
p3 task create --feature-id <featureId> --name "Assign me" --assigned-to-id <userId>
p3 task create --feature-id <featureId> --name "Assign me" --assigned-to-id @hazel
p3 task create --feature-id <featureId> --name "Linked" --linked-task-id <id> --linked-task-type 1
p3 task create --project-id <projectId> --name "Improve onboarding"

Notes:

• @username resolves to the assignee's profile username (set in Profile -> Username)
• --assignTo and --assignedTo are supported aliases for --assigned-to-id
• after creating a task in an interactive terminal, the CLI prints the task URL and asks whether to set it as the current task (default: yes)

Create Many

Interactive mode:

p3 task create-many
p3 task create-many --apply "--project-id <projectId> --assignTo @hazel"
p3 task create-many --dry-run

Enter one task per prompt line using the same syntax as p3 task create. Submit a blank line to finish.

Example prompt lines:

Fix auth redirect --assignTo @hazel
Improve onboarding --description "Shorten first-run flow"
Linked follow-up --linked-task-id <id> --linked-task-type 1

File mode:

- Add loading state --assignTo @hazel
- Add loading state in modal --project-id <projectId>
- Fix auth redirect --description "Skip select-user fetch"
- Improve onboarding --name "Improve onboarding copy"
- Update CLI docs
1. Numbered items also work

Use the same line format in a file, then preview or create them:

p3 task create-many --file tasks.txt --dry-run
p3 task create-many --file tasks.txt
p3 task create-many --file tasks.txt --apply "--project-id <projectId> --assignTo @hazel"

Behavior:

• p3 task create-many starts interactive entry mode
• p3 task create-many --file tasks.txt reads one task per line from a file
• blank lines and # comments are ignored
• leading list markers like -, *, +, and numbered prefixes like 1. are ignored
• each line supports the same create options as p3 task create
• --apply adds shared options to every line
• per-line options override --apply
• interactive runs show a confirmation table before submit
• file runs use the same parser and preview/creation flow as interactive runs
• partial failures are reported after the run

Update

p3 task update <taskId> --status "Working on it"
p3 task update <taskId> --priority high --assigned-to-id <userId>
p3 task update <taskId> --assignedTo @hazel
p3 task update <taskId> --tag-ids id1,id2 --action Build
p3 task assign <taskId> --user-id <userId>
p3 task assign --task-ids id1,id2 --user-id <userId>

Bulk update

p3 task update-many --task-ids id1,id2 --status Done

Convenience commands

p3 next  # -> alias of `p3 task next`
p3 task next  # -> returns the highest-priority active task assigned to you
p3 open  # -> open the selected task in the browser (taskp3.com/p/<projectId>?selectedTaskId=<id>)
p3 done  # -> marks the current task Done (or prompts to pick one), then asks to checkout development
p3 task done <taskId>  # -> marks the provided task Done

Current Task

p3 current
p3 task current
p3 current set <taskId>
p3 current clear

Current task resolution order:

• repo-scoped selected task from CLI config
• current branch task id suffix, if detectable

Current Project

p3 project current
p3 project select

Webhook Listener

Forward webhook events to a local URL during development — no tunnel required when running the API locally.

p3 listen --forward-to http://localhost:3000/webhooks
p3 listen --forward-to http://localhost:3000/webhooks --project-id <id>

The CLI polls for new webhook events and forwards each one to the target URL with the same x-p3-signature header format used in production. A local signing secret is printed at startup so your app can verify signatures identically to production.

Uses the default project if --project-id is omitted.

Enum Values (validated)

Use these values (case-insensitive). Aliases like InProgress are normalized.

• status: Not Started, Stuck, Working on it, Done, Cancelled, In Review
• priority: low, medium, high, critical
• action: N/A, Build, Design, Debug, Fix, Enhance, Research

Output

Commands print concise human-readable output by default.

Use --json for full JSON output:

p3 --json task get <taskId>

Example JSON:

{
  "task": {
    "id": "123",
    "name": "Improve onboarding",
    "status": "Working on it"
  }
}

Advanced

Base URL

API base URL (default https://api.taskp3.com) is used for all CLI API calls. App base URL (default https://www.taskp3.com) is used for p3 open and task links; it is derived from the API URL unless set separately (e.g. for local dev: API on one port, app on another). Override with:

p3 config:set --base-url http://localhost:3001
p3 config:set --app-base-url http://localhost:3000

Or on a single command:

p3 auth status --base-url http://localhost:3001

Config

You usually do not need to set a project manually:

• On the first p3 task create (or p3 listen) without --project-id, the CLI auto-selects when there is one project, or prompts you to choose when there are multiple.
• The chosen project is saved per local repo (git root), so context switching across repos keeps separate defaults.

Optional manual overrides:

p3 config:set --base-url http://localhost:3001
p3 config:set --app-base-url http://localhost:3000
p3 config:set --default-project-id <projectId>
p3 config:set --default-project-id <projectId> --global
p3 config:view

Shell Completion

Generate completion scripts for your shell:

# Bash - add to ~/.bashrc
eval "$(p3 completion bash)"

# Zsh - add to ~/.zshrc
eval "$(p3 completion zsh)"

# Fish - save to completions directory
p3 completion fish > ~/.config/fish/completions/p3.fish

Environment Variables

| Variable | Description | | ------------- | ---------------------------------------- | | P3_API_URL | Override the default API base URL | | P3_APP_URL | Override the default web app base URL | | P3_DEBUG | Set to 1 to enable debug output |

Debug Mode

For troubleshooting, enable debug output:

# Via environment variable
P3_DEBUG=1 p3 task list

# Via flag
p3 --debug task list

Exit Codes

| Code | Meaning | | ---- | ----------------------- | | 0 | Success | | 1 | General error | | 4 | Authentication required |