pcli/openspec/changes/archive/2026-03-04-project-export-import/proposal.md at main

steve/pcli

Files

T

steve e973b2ce20 feat: add project export and import functionality

- Implemented `pcli project export` command to export project hierarchy as JSON.
- Added `pcli project import` command to import project data from JSON.
- Created user client to fetch user details for comment attribution.
- Introduced new data structures for export and import processes.
- Ensured name-based references in exports and handled conflicts during imports.
- Added versioning and progress reporting for import operations.
- Updated documentation and specifications for new features.

2026-03-04 19:53:55 +00:00

4.2 KiB

Raw Permalink Blame History

Why

There's no way to backup, migrate, or clone project data between Planka instances using pcli. Users need to export a project (or specific board) to a portable file and import it elsewhere — useful for backups, instance migration, and sharing project templates.

What Changes

Add pcli project export command: exports a project (optionally filtered to a specific board) as a self-contained JSON file to stdout
Add pcli project import command: reads a JSON export file and creates the project/board(s) on the target instance
Export uses names (not IDs) as the portable identity — IDs are Planka-instance-specific and regenerated on import
Export includes the full hierarchy: project → boards → lists → labels → cards → card-labels → task lists → tasks → comments
Import uses fail-if-exists strategy: if the project+board name combination already exists on the target, import stops with an error. Project existing alone is fine (board gets added to it).
User-specific references (cardMemberships, creatorUserId) are excluded from export — these are instance-specific and not portable
Comments are exported with text attribution: each comment is prefixed with (Original comment by <username>) so authorship is preserved textually even though the userId is not portable. This requires a one-time user list fetch during export to resolve userId→name.

Export format

Single JSON object to stdout. Structure:

{
  "version": 1,
  "exportedAt": "2026-03-04T...",
  "project": {
    "name": "...",
    "description": "...",
    "boards": [
      {
        "name": "...",
        "position": 1,
        "lists": [...],
        "labels": [...],
        "cards": [
          {
            "name": "...",
            "listName": "...",
            "labelNames": ["..."],
            "description": "...",
            "taskLists": [
              {
                "name": "...",
                "tasks": [{ "name": "...", "isCompleted": false }]
              }
            ],
            "comments": [{ "text": "(Original comment by jsmith)\nActual comment text here" }]
          }
        ]
      }
    ]
  }
}

Key design choices:

Name-based references: cards reference listName and labelNames instead of IDs
Nested hierarchy: no ID cross-references to resolve — everything is inline
Version field: allows future format changes
Positions preserved to maintain ordering
User fields stripped (not portable) except for textual attribution on comments
Comments prefixed with (Original comment by <username>) — requires fetching user list during export to resolve userIds to names. If a userId can't be resolved, falls back to (Original comment by unknown user)

Import behavior

Look up project by name — create if it doesn't exist
For each board in the export: check if project already has a board with that name → fail with error if so
Create board, then lists, labels, cards (mapping listName→list ID, labelNames→label IDs), task lists, tasks, comments — all with fresh Planka IDs
Ordering maintained via position fields from the export

CLI interface

pcli project export <project-id-or-name> [--board <name-or-id>] > backup.json
pcli project import < backup.json
# or
pcli project import --file backup.json

Capabilities

New Capabilities

project-export: Export project hierarchy to portable JSON (project → boards → lists → labels → cards → task lists → tasks → comments)
project-import: Import project hierarchy from JSON export file, creating all resources with new IDs

Modified Capabilities

(none — these are new commands added to the existing project resource)

Impact

New files: client/export.go, client/import.go, client/users.go, cmd/export.go, cmd/import.go
Model changes: new export-specific types in model/types.go (portable structs without IDs/user references), new User type
API usage: export requires multiple API calls (user list for name resolution, board GET for bulk data, then per-card fetches for comments/tasks) — could be slow for large projects
No breaking changes: purely additive new subcommands
Dependencies: none new (standard library JSON encoding)

4.2 KiB Raw Permalink Blame History

Why