# Imports
Import commands use Wekan v12.57's native REST endpoints. They accept ordinary
files or `-` for stdin, require stored credentials, and run directly without a
confirmation prompt. Use `--output json` for stable machine-readable results.
They do not retry requests: repeated imports create additional resources.
## Trello HTTP import
```console
wekan board import-trello trello.json --format json --members-mapping-file members.json
wekan board import-trello boards.zip --format zip
This command calls `POST /import-trello`, creating new boards. It accepts an
unwrapped Trello JSON board object or a raw Trello attachment ZIP; `--format
`--members-mapping <JSON>` or `--members-mapping-file <PATH>` supplies a JSON
object mapping Trello member IDs to Wekan user IDs. These forms conflict; the
mapping file must be regular and cannot be `-`. Mapping is JSON-only. Wekan can
use its saved Trello API credentials to retrieve assets during JSON imports;
the CLI does not download or replace assets.
`--auth <bearer|x-auth-token|meteor-cookie|wekan-cookie>` defaults to Bearer.
All four forms use the selected profile's stored login token. Cookie modes send
`meteor_login_token` or `wekan_login_token`; no token is supplied as a command
argument or query parameter. There is no authentication fallback.
Results contain `format` and `board_ids`. ZIP
results also contain `errors`, including an empty array for full success. Each
failure contains `board` and `error`; failed scalar board names retain their
string, number, or boolean type. Composite or null names, missing required
values, and unknown response fields fail with `protocol_error`.
**Any ZIP board failure returns `batch_incomplete` (exit 5)** even though Wekan
returns HTTP 200. All returned IDs and failures remain available in
`error.details.trello_import_result` and human error output. Failed imports can
leave additional boards whose IDs were not returned, including JSON failures
with HTTP 400. Errors after submission preserve native diagnostics and
`retry_safe: false`. Inspect saved state before another import; no rollback or
automatic retry occurs.
ZIP attachment files must match Wekan's native board-name folder or filename
prefix rules; the root-file fallback applies only to a single-board ZIP.
JSON inputs, member maps, and the final wrapped JSON request have a 50 MiB limit.
Trello ZIP uploads have a 200 MiB compressed client limit. ZIP stdin is staged on
disk, then streamed with a known length. Wekan applies its own 5000-file, 1 GiB
declared uncompressed total, 100 MiB per declared file, and path checks. The CLI
passes the archive intact for native validation. `--timeout` accepts positive
integer seconds and defaults to 30. Only human/JSON output is supported, and
there is no `--yes` option.
## New boards
```console
wekan board import board.json
wekan board import trello.json --source trello
wekan board import cards.csv --source csv --delimiter ";"
wekan board import cards.tsv --source csv --delimiter '\t'
wekan board import workbook.xlsx --source excel
wekan board import issues.json --source github --members-mapping-file members.json
```
Omitting `--source` selects `POST /api/boards/import`. An explicit source selects
`POST /api/boards/import/{source}`, including `--source wekan`. Supported sources
are all 49 keys in the pinned catalog:
```text
wekan trello csv excel jira kanboard deck openproject
github gitlab gitea forgejo asana zenkit markdown leo
opml orgmode todotxt taskwarrior focalboard todoist planner meistertask
obsidian linear ticktick clickup nullboard kanri pivotal redmine
tasksorg monday superproductivity taiga vikunja wrike teamwork businessmap
quire notion plane planka mstodo kanbanflow basecamp googletasks
googlekeep
```
The source is explicit. Plane, Notion, and Vikunja detect ZIP/XLSX encodings
from the filename extension when `--input-format auto` is used. For stdin or an
unusual extension, set `--input-format json|text|xlsx|zip` explicitly. Plane
accepts JSON/CSV text, XLSX, or ZIP; Notion accepts database CSV text or ZIP;
Vikunja accepts data.json text or ZIP. Other sources use their native encoding:
Excel, Planner, Monday, Wrike, Teamwork, and Businessmap use workbook bytes;
text/XML/JSON Lines source engines receive unchanged UTF-8 text; the remaining
JSON sources accept an
export document (object or array). The CLI preserves its properties and wraps
the entire document in the request's `board` property. Supply the export itself,
including Kanboard's own `board` header, rather than an API request wrapper.
Wekan interprets the platform's document and validates its contents.
CSV input is UTF-8 text with a header row. The CLI sends all records as arrays
of strings, retaining the header, quoted delimiters, multiline fields, field
whitespace, empty fields, record order, and variable record lengths. Empty
physical lines are skipped by the CSV reader. Wekan recognizes headers such as
`title`, `description`, `stage`, `members`, and `due date`; it interprets dates
and members. `--delimiter` is CSV-only, defaults to comma, and accepts one ASCII
character other than NUL, CR, LF, or double quote, or the literal `\t` for tab.
Excel input is XLSX bytes, encoded as `excelBase64`; Wekan reads its first sheet.
It treats those rows as tabular card data. The default detailed board XLSX
export contains report rows, which can become extra cards when imported.
Verify imported lists, cards, and fields rather than assuming an export/import
round trip preserves the board.
Optional member mapping is an object of source identifiers to local Wekan user
IDs, for example `{"upstream-alice":"local-user-id"}`. Use either
`--members-mapping <JSON>` or `--members-mapping-file <PATH>`. The mapping file
must be a regular UTF-8 JSON file; `-` is reserved for the main document input.
Mapping behavior belongs to the selected importer. For example, CSV adds mapped
card members and omits unmapped ones. This command performs no account lookup
or reconciliation.
The board result contains `board_id` and `source` (`native` when omitted).
## ZIP into an existing board
```console
wekan board import-zip board.zip --board BOARD_ID
wekan board import-zip board.zip --board BOARD_ID --list LIST_ID --field description --field comments
wekan board import-zip board.zip --board BOARD_ID --card CARD_ID --timeout 120
```
The complete ZIP is sent as `application/zip`, containing `wekan.json` and
optional `attachments/<id>-<filename>` entries. Files are streamed from an open
regular-file handle; stdin is staged on disk before the request and removed
afterwards. Archives are not extracted or rewritten by the CLI.
Optional `--swimlane`, `--list`, `--card`, and `--checklist` selectors are sent
together as supplied. Scope IDs require 1–64 ASCII letters, digits, underscores,
or hyphens. Native card scope takes precedence over list and swimlane scope.
**Wekan v12.57 ignores checklist scope**, so `--checklist` alone can still import
the whole document into the destination board. No client emulation occurs.
Repeat `--field` for selected sections: `card-details`, `board-header`,
`activities`, `labels`, `people`, `board-info`, `dates`, `description`,
`custom-fields`, `checklists`, `subtasks`, `comments`, `attachments`, `voting`,
`poker`, `stickers`, `locations`, `dependencies`, or `sort`. Values are joined
into one native `fields` parameter; Wekan decides each section's import effect.
Omission leaves native selection defaults.
Bearer authentication is the default. `--auth-token-query` explicitly sends the
stored token through `authToken` instead. There is no authentication fallback.
The ZIP result includes `board_id`, requested `swimlane_id`, `list_id`, `card_id`,
and `checklist_id` (null when absent), and `counts`.
The six counts are `swimlanes`, `lists`, `cards`, `checklists`, `comments`, and
`attachments`. Requested selectors do not prove that Wekan honored them.
## Calendar events as cards
```console
wekan card import-ics events.ics --board BOARD_ID --swimlane-id SWIMLANE_ID --list LIST_ID
```
UTF-8 calendar contents are sent in the native `ics` JSON property. Wekan creates
cards from VEVENTs, using DTSTART for `startAt` and DTEND for `dueAt`, or DTSTART
when DTEND is absent. The CLI does not parse, normalize, or synchronize events.
The result contains `board_id`, `swimlane_id`, `list_id`, `created`, and `card_ids`.
Human output reports completed imports, including the count and card IDs.
## Limits and errors
JSON, CSV, XLSX, ICS, and member mapping inputs each have a 50 MiB acquisition
limit. The final serialized JSON request also has a 50 MiB limit, including
wrapping, escaping, member mapping, and base64 expansion. Consequently the
largest accepted XLSX is smaller than 50 MiB. Native `board import-zip` input has a 5 GiB client limit;
the server may impose a lower configured limit. Invalid local input fails with
`invalid_input` (exit 2); acquisition/staging I/O errors use `file_io_error`
(exit 4). Regular files and stdin are supported; directories and named pipes
are rejected as file inputs.
Every command accepts `--timeout <SECONDS>` with a positive integer; default
30 seconds. All existing global server/profile/output/network options apply.
Raw output and `--yes` are unsupported.
Native import failures retain their actual non-success HTTP status and safe
server error. Invalid Wekan document shapes currently return HTTP 500 with
`Internal server error`; they do not produce a successful empty response. Unknown response fields, including nested ZIP counters, are
also protocol errors. The existing error envelope preserves native HTTP/error
metadata.
Missing ZIP boards retain HTTP 404. ICS missing boards or insufficient write
permission return `permission_denied`, retaining HTTP 401 and `not-authorized`
without advising credential replacement; missing lists/swimlanes on an accessible
board retain HTTP 500 HTML errors.
Native ZIP attachment imports now complete and preserve actual file bytes; the
old Meteor-Files callback hang and temporary-file leak are fixed (W11-032).
## Member handling and source options
`board import` and `board import-trello` accept `--members-mode map|placeholder|me`.
For `board import`, this option requires an explicit `--source`; use
`--source wekan --members-mode me` for a Wekan export. The endpoint selected
when `--source` is omitted ignores member modes, so the CLI rejects this
combination before acquiring input, accessing credentials, or sending HTTP.
The native default is `placeholder`: imported people become non-login placeholder
accounts until a board administrator maps them. `map` uses the supplied member
map and creates placeholders for unmapped people. `me` attributes people to the
importing user, while retaining explicit mappings. Trello JSON sends this in the
body; Trello ZIP sends `membersMode` in the query.
General board imports also accept `--split-by swimlane`, `--csv-mapping JSON`,
and `--attachment-auth-file PATH`. CSV mapping applies only to CSV and Excel:
its typed keys are `columns` (field-to-column-number object), `listName`, and
`customFieldColumns` (column numbers). Attachment authentication accepts optional
`url`, `username`, and `token` strings in a regular JSON file; it is supplied to
the server for that import's attachment downloads. The CLI does not print it.
These options preserve the selected native source engine's behavior. Splitting
does not change the native single-ID response, so inspect destination state when
the server imports several projects or workbook sheets.
### Import a ZIP as a new board
`wekan board import-zip board.zip --new-board` uses the native `newBoard=1`
mode and returns `board_id` and `source: "wekan-zip"`. Choose exactly one of
`--board BOARD_ID` and `--new-board`. `--members-mode map|placeholder|me`
is available with `--new-board`; scoped destination selectors require `--board`.
Field selection, file/stdin acquisition, authentication and timeout controls
work in both modes. New-board imports do not return scoped resource counters.
The new-board ZIP mode currently returns HTTP 500 `import-failed` for valid
native exports because the server starts the import outside its user context
(W12-005). Scoped import completes, but native ZIP exports name attachment
entries differently from the ID-prefixed format this importer expects and can
therefore import cards with zero attachments (W12-004). The CLI preserves the
native response and never rewrites archives or substitutes an import engine.