Skip to main content
@kaneo/planka-import reads your boards directly from PLANKA’s REST API and recreates them in Kaneo through Kaneo’s public API. The CLI reads from PLANKA and writes directly to your Kaneo instance. It does not modify PLANKA or use an intermediary migration service.

​
Before you start

You need:
  • A PLANKA account that can see the boards you want to move. If you sign in through SSO and have no password, create a PLANKA API key and use --planka-api-key.
  • A Kaneo workspace, and an API key from Settings → Account → API Keys.
  • Node.js 20 or newer.
Use a PLANKA administrator account if you want to preserve assignees. PLANKA hides other users’ email addresses from non-administrators, which prevents email matching. Invite your team to the Kaneo workspace before importing. Assignees are matched by email address, so anyone who isn’t a member yet will have their cards imported unassigned.

​
Start with a dry run

A dry run reads PLANKA only and writes nothing. It needs no Kaneo API key, so it’s a safe first step:
You’ll be asked for your PLANKA login and which boards to migrate. The output tells you exactly what would be created:

​
Run the import

When the plan looks right, set KANEO_API_KEY in your environment and drop --dry-run. The CLI reads the key from that variable:
Self-hosting Kaneo? Point --kaneo-url at your own instance. If you leave --workspace off, you’ll be asked to pick one. To skip the prompts entirely, for example in a script:
Set PLANKA_PASSWORD and KANEO_API_KEY as environment variables rather than passing secrets on the command line, where they end up in your shell history.

​
What carries over

One Kaneo project is created per PLANKA board, because the board is what holds the lists and cards. When a PLANKA project has more than one board, each resulting Kaneo project is named Project - Board.

​
What doesn’t

  • Attachments. Counted in the report, but not transferred. Download anything you need from PLANKA before you switch it off.
  • Archive and trash lists. Skipped deliberately; only active and closed lists are migrated.
  • Comment authorship. The comment is created by the API key’s owner, but the original PLANKA author is recorded on it and shown in Kaneo, the same way imported GitHub comments are. This needs Kaneo 2.17.6 or newer; against older instances the comment still imports, just without the original author.
  • Priorities. The importer sets every task to no-priority.
  • Custom fields, stopwatches, and card subscriptions. The importer does not transfer these. Kaneo supports custom fields and time entries, but you need to recreate that information yourself.

​
Troubleshooting

“This PLANKA instance requires you to accept its terms”: sign in through the PLANKA web UI once and accept them, then run the import again. Two-factor authentication, or an SSO-only account: password login either can’t complete a TOTP challenge, or there is no local password at all. Create a PLANKA API key for the account and pass --planka-api-key instead. This is the recommended credential: it doesn’t expire the way a copied session token does. A board failed partway: failures are isolated per board, so the rest still import and the summary names the one that failed. Delete the half-created Kaneo project and run the importer interactively again, selecting only the failed board. The --project flag filters PLANKA projects, which can contain several boards.

​
Re-running

The importer always creates new projects; it never updates ones it created earlier. Running it twice gives you two copies, so delete the previous project before retrying.

​
Options