logseq/docs/agent-guide/006-logseq-cli-import-export.md

# Logseq CLI Import/Export Plan

Goal: Add logseq-cli support for import/export with EDN and SQLite formats using the existing db-worker-node server.

Architecture: Extend logseq-cli command parsing and execution to invoke db-worker-node thread APIs for export and import, with minimal new APIs to handle EDN import and SQLite binary payloads over HTTP.

Tech Stack: ClojureScript, babashka/cli, db-worker-node HTTP /v1/invoke, datascript, sqlite-export helpers, Node fs/path.

Related: Builds on docs/agent-guide/004-logseq-cli-verb-subcommands.md and docs/agent-guide/003-db-worker-node-cli-orchestration.md.

## Requirements

- Import types: edn, sqlite.
- Export types: edn, sqlite.
- CLI must work against db-worker-node with repo binding and lock file behavior.
- Output files must be written to user-specified paths with clear success/error messages.

## Proposed CLI UX

Prefer graph-scoped subcommands to keep import/export with graph management:

- `logseq graph export --type edn --file <path> [--graph <graph>]`
- `logseq graph export --type sqlite --file <path> [--graph <graph>]`
- `logseq graph import --type edn --input <path> --graph <graph>`
- `logseq graph import --type sqlite --input <path> --graph <graph>`

Notes:
- `graph import` only supports importing into a new graph name; it must not overwrite an existing graph.
- `--graph` is required for import, and required unless the current graph is set in config for export.

## Current Capabilities (Baseline)

- db-worker-node supports `:thread-api/export-edn`, `:thread-api/export-db`, and `:thread-api/import-db`.
- logseq-cli can invoke db-worker-node via `src/main/logseq/cli/transport.cljs` and write files with `transport/write-output`.
- EDN import exists in the app layer (`frontend.handler.db-based.import`) but not in db-worker-node.
- SQLite import in db-worker-node writes the sqlite file, but CLI needs a full reload step to reflect new data.

## Implementation Plan

1. Review existing CLI command table and action pipeline in `src/main/logseq/cli/commands.cljs` and `src/main/logseq/cli/main.cljs` to locate insertion points for new graph import/export actions.
2. Add new CLI specs for import/export flags (type, input, output, export-type, mode) in `src/main/logseq/cli/commands.cljs`.
3. Extend the command table with `graph import` and `graph export` entries and ensure help output includes them.
4. Add action builders for import/export that validate repo presence, file paths, and allowed types (edn, sqlite).
5. Add CLI helpers for reading input files and writing output files in `src/main/logseq/cli/transport.cljs` (or a new helper namespace), keeping the existing `write-output` behavior for EDN and DB files.
6. Implement export execution:
   - EDN: call `thread-api/export-edn` (graph-only) and write EDN file.
   - SQLite: call a new db-worker-node export API that returns a base64 string or transit-safe binary; decode to Buffer and write `.sqlite` file.
7. Implement import execution:
   - EDN: read EDN file, pass data to a new db-worker-node `thread-api/import-edn` (see below), and return a summary message.
   - SQLite: read file as Buffer, pass to a new db-worker-node `thread-api/import-sqlite` (or reuse `import-db` with a wrapper that closes/reopens the repo).
   - Always stop and restart the db-worker-node server from the CLI around import to ensure a clean reload.
8. Add db-worker-node thread APIs in `src/main/frontend/worker/db_core.cljs`:
   - `:thread-api/import-edn` to convert export EDN into tx data via `logseq.db.sqlite.export/build-import` and transact with `:tx-meta` including `::sqlite-export/imported-data? true` so the pipeline rebuilds refs.
   - `:thread-api/export-db-base64` (or similar) to return a base64 string for SQLite export over HTTP.
   - `:thread-api/import-db-base64` (or similar) to accept base64 input, close existing sqlite connections, import db data, and reopen the repo (or invoke `:thread-api/create-or-open-db` with `:import-type :sqlite-db`).
9. Update db-worker-node server validation (repo binding) if the new thread APIs need special argument shapes.
10. Update CLI output formatting in `src/main/logseq/cli/format.cljs` to print concise success lines like `Exported <type> to <path>` and `Imported <type> from <path>`.
11. Update documentation in `docs/cli/logseq-cli.md` with new commands, examples, and file format notes.

## Testing Plan

- Add CLI parsing tests for `graph import` and `graph export` options in `src/test/logseq/cli/commands_test.cljs` (or a new namespace).
- Add integration tests in `src/test/logseq/cli/integration_test.cljs` to:
  - export EDN and SQLite from a test graph and assert output files exist and are non-empty.
  - import EDN into a new graph and verify a known page/block exists via CLI `show` or `list`.
  - import SQLite into a new graph and verify graph metadata or page count.
- Add db-worker-node tests in `src/test/frontend/worker/db_worker_node_test.cljs` for the new import/export thread APIs (EDN build-import path and base64 DB export/import).
- Follow @test-driven-development: write failing tests before implementation.

## Edge Cases

- Large SQLite exports may exceed JSON limits if not base64/transit encoded; ensure streaming-safe or chunked base64 handling.
- Import should fail fast if the repo is missing and `--graph` is not provided, or if input file does not exist.
- SQLite import while the repo is open must close/reopen connections to avoid stale datascript state.
- EDN import should validate the export shape and surface readable errors when EDN is invalid or incompatible.
- Overwrite behavior should be explicit for SQLite imports to prevent accidental data loss.

## Decisions

1. `graph import` only imports into a new graph; it must not overwrite an existing graph.
2. No `--mode` flag; both EDN and SQLite imports are replace-style imports.
3. CLI always stops and restarts db-worker-node around imports.
4. `graph export --type edn` is graph-only for now (no page/view/blocks).