Skip to main content

Import from ClickUp

Hearth can take over a ClickUp workspace. Three hearthctl commands do it, in order: import-clickup brings the work across, clickup-gap adds what the first pass leaves out, and verify-clickup reads both sides and proves they match. It is a migration, so it runs as a command you can watch, not a button.

hearthctl ships in the same image as Hearth. Run it as a one-off job on the live image with the same settings as the Hearth deployment, dry run first. You need a ClickUp personal API token, which starts with pk_, and the Hearth database address.

1. Import​

hearthctl import-clickup -token pk_... -dry-run

The dry run walks the workspace and prints, for each space, how many lists and tasks it would bring across. It writes nothing. When the numbers look right, run it again without -dry-run.

FlagWhat it does
-tokenThe ClickUp token, or the CLICKUP_TOKEN variable
-dsnThe Postgres address, or HEARTH_DATABASE_URL
-spaceImport only this ClickUp space, by name. Empty means all of them
-dry-runWalk and report, write nothing
-peopleMake an account for each workspace member so assignees resolve. On by default
-docsAlso import the workspace's documents as wiki pages. On by default
-commentsAlso import task comments. Off by default, because it takes one request per task and is the slowest part on a large workspace
-archivedInclude archived folders and lists

Every task is matched on its ClickUp id, so running it twice updates what it already brought in and never duplicates it.

2. Fill in what the import left out​

hearthctl clickup-gap reads ClickUp again and adds only what Hearth is missing: task attachments, comments past the first 25, each person's own time instead of one total, anything made after the first import finished, and any space the first token could not open.

  • snapshot reads ClickUp, read only, saves the whole read to Hearth's object store, and prints a comparison per space of what ClickUp has and Hearth does not.
  • apply -dry-run prints the same comparison from a saved read.
  • apply writes.

What apply keeps to:

  • It matches on the ClickUp id the first import stored, so a second run adds nothing.
  • A task changed in ClickUp is brought up to date only if Hearth's copy has not been edited since the first import. An existing task's owner and creator are never touched, and nothing sends a notification.
  • New tasks go in the department their list belongs to, assigned to the person ClickUp named if they can still sign in. A name with no active account, and a task with none at all, goes to the fallback person you name with -fallback.
  • Attachments are downloaded into Hearth's object storage and attached to their task. A comment by someone with no account says who wrote it.
  • Time goes on the right person. A task's one-total entry from the first import is hidden, not deleted, once per-person entries exist for it.
  • Every row written is printed as an UNDO line and saved to the object store as imports/clickup-gap-undo-<time>.log.

To run it: take a backup first, take a snapshot, read the comparison, run apply -snapshot-key <key> -dry-run, then apply without the dry run, then take another dry run and expect every "missing" column to be zero.

Each UNDO line names what was written: a document, a message, a file, a time entry, an update restored from the document's history, or a retired time entry whose hidden mark is cleared. You can also put the whole database back from the backup you took first.

3. Verify​

hearthctl verify-clickup -token pk_...

A count printed by the import is only what the import believes it did. verify-clickup reads ClickUp and Hearth independently and answers three questions: is everything there, is anything extra, and did the fields arrive, counted rather than assumed: assignees, real dates, statuses, and custom values.