PlanFlow CLI

PlanFlow CLI is a Node.js command line client for maintaining PlanFlow project groups, projects, stages, and stage participants.

Package name:

npx @agilebuilder/planflow-cli <command>

Local development:

cd cli
npm install
npm run dev -- <command>

Configuration

The CLI reads configuration from ~/.planflow/config.json by default. You can also override config per command.

planflow config set-url http://127.0.0.1:8080
planflow config set-api-key pfk_xxx
planflow config show
planflow whoami

Global options:

planflow --json <command>
planflow --config ./planflow.config.json <command>
planflow --base-url http://127.0.0.1:8080 --api-key pfk_xxx <command>
planflow --help
planflow --version

Authentication uses:

Authorization: Bearer <apiKey>

Status Rules

Project status is read-only in business terms. It is derived by the backend from project stages:

• no stages: unscheduled
• any overdue: overdue
• otherwise any paused: paused
• otherwise any in_progress: in_progress
• all completed: completed
• all not_started: not_started
• mixed remaining statuses: in_progress

For compatibility, projects create and projects update still accept --status, but the CLI does not send it to the backend. New scripts should not use project --status.

Stage status can be maintained with --status. Supported values are:

• not_started
• in_progress
• completed
• paused
• overdue

The CLI also accepts common aliases such as uppercase values and active, then normalizes them before calling the backend.

Project Groups

List groups:

planflow groups list
planflow --json groups list

Create a group:

planflow groups create \
  --name "研发平台组" \
  --description "平台和工具团队"

Update a group:

planflow groups update <groupId> \
  --name "研发一组" \
  --description "核心业务研发团队"

Delete a group:

planflow groups delete <groupId>

Users

Read synced PlanFlow users:

planflow users list
planflow --json users list

Use users list to resolve project owner IDs and stage participant user IDs before creating or updating data.

Projects

Projects belong to project groups. Project dates and project status are calculated from stages.

List projects:

planflow projects list
planflow --json projects list

Show project detail:

planflow projects get <projectId>

Create a project:

planflow projects create \
  --group <groupId> \
  --name "PlanFlow 二期" \
  --owner <userId> \
  --description "完善 CLI 和报表能力"

Update a project:

planflow projects update <projectId> \
  --group <groupId> \
  --name "PlanFlow 二期优化" \
  --owner <userId> \
  --description "更新后的项目说明"

Delete a project:

planflow projects delete <projectId>

Notes:

• --group and --name are required for create and update.
• --owner and --description are optional.
• --status is deprecated for project commands and is ignored.
• Deleting a project physically deletes the project and cascades deletion of its stages and stage participants.

Stages

Stages carry the schedule. Dates are inclusive and use YYYY-MM-DD.

List stages under a project:

planflow stages list --project <projectId>
planflow --json stages list --project <projectId>

Show stage detail:

planflow stages get <stageId>

Create a stage:

planflow stages create \
  --project <projectId> \
  --name "开发阶段" \
  --start 2026-06-01 \
  --end 2026-06-20 \
  --status not_started \
  --description "功能开发和联调"

Update a stage:

planflow stages update <stageId> \
  --name "联调阶段" \
  --start 2026-06-15 \
  --end 2026-06-25 \
  --status in_progress \
  --description "跨系统联调"

Delete a stage:

planflow stages delete <stageId>

Notes:

• --project, --name, --start, and --end are required when creating a stage.
• --name, --start, and --end are required when updating a stage.
• Stage end date can equal start date.
• Stage end date cannot be earlier than start date.
• If only changing one field, first run stages get, then pass unchanged required fields back to stages update.

Participants

Participants are assigned to stages, not directly to projects.

List participants:

planflow participants list --stage <stageId>

Add or replace selected users while keeping other participants:

planflow participants add \
  --stage <stageId> \
  --user zhangsan lisi \
  --role Developer \
  --allocation 100

Remove selected users:

planflow participants remove \
  --stage <stageId> \
  --user zhangsan lisi

Replace the full participant list for a stage:

planflow participants set \
  --stage <stageId> \
  --user zhangsan lisi \
  --role Developer \
  --allocation 100

Notes:

• participants add is preferred for routine maintenance.
• participants set is destructive because it replaces the whole list.
• --allocation defaults to 100 and represents allocation percent.

Common Workflows

Configure access:

planflow config set-url http://127.0.0.1:8080
planflow config set-api-key pfk_xxx
planflow whoami

Create a scheduled project:

planflow --json users list
planflow --json groups list
planflow projects create --group <groupId> --name "门户改造" --owner <userId>
planflow stages create --project <projectId> --name "需求分析" --start 2026-06-01 --end 2026-06-07 --status in_progress
planflow stages create --project <projectId> --name "开发阶段" --start 2026-06-08 --end 2026-06-28 --status not_started
planflow participants add --stage <stageId> --user zhangsan lisi --role Developer --allocation 100

Move a stage without losing fields:

planflow --json stages get <stageId>
planflow stages update <stageId> --name "<existingName>" --start 2026-07-01 --end 2026-07-20 --status <existingStatus> --description "<existingDescription>"

Read schedule data for scripting:

planflow --json projects list
planflow --json stages list --project <projectId>
planflow --json participants list --stage <stageId>

Error Handling

Missing configuration:

Missing baseUrl. Run: planflow config set-url <url>
Missing apiKey. Run: planflow config set-api-key <apiKey>

Invalid authentication:

UNAUTHORIZED: Invalid API Key

When a write command fails, stop dependent writes, keep the returned backend error, and verify current data before retrying.