Moving projects to another device

Istok keeps everything in a local database. To continue on another machine, export the projects you need on one device and import the file on the other. There is no automatic sync yet: you decide when to move data.

Both devices must run the same Istok version. Run istok update on both first.

What moves and what stays

The export file carries what you need to continue the work:

• projects (their names and IDs, not their folders);
• tasks with their history, dependencies and completions;
• runs, the commands they ran and their validations;
• what each agent saw at claim time, without the code snippets;
• shared project rules, context and knowledge.

These stay on the device where they were made:

• project folders: each device has its own paths;
• command output (stdout and stderr logs);
• the code index, which each device builds for itself;
• code snippets that agents received from the index;
• context and knowledge marked local_only;
• deleted projects.

The file contains your task history and project notes. Treat it like a private document.

Export

From the repository of the project:

istok export

This writes istok-export-<date>-<time>.json in the current directory. To choose projects or a file name:

istok export --project acme-api --project billing-worker -o work.json
istok export --all -o everything.json

In the web UI, open a project and choose Export project in the ⋯ menu, or use Export all on the projects page.

Import

Copy the file to the other device and look at what would change first:

istok import work.json --dry-run

Then import it:

istok import work.json

In the web UI, use Import on the projects page. It shows the same preview before anything is written.

The report lists each project as new or merged, how many tasks, runs and other records were added or updated, tasks that got a new number, and anything that needs your attention.

Bind the folder

An imported project has no folder on the new device yet. You can see its tasks and history, but agents cannot work on its code until you bind the repository:

1. Clone the repository.

2. Bind the folder in the web UI: open the project and choose Bind folder. Or from the terminal:

   istok project rebind acme-api ~/src/acme-api

Istok never guesses which folder belongs to a project. If the same repository is already registered on this device as a separate project, the import warns you; keep one of them and bind its folder.

How changes merge

You can export and import in both directions as often as you like. Importing the same file twice changes nothing.

• Tasks, context and knowledge: the version with more changes wins. If the same item was changed on both devices since the last exchange, the version on the device you import into is kept, and the report lists a conflict.
• History, runs and validations are added; nothing is lost.
• Deletions move too: a task, rule or note deleted on one device is deleted on the other.
• Task numbers: if both devices created a task with the same number while apart, the task created later gets the next free number. Its history records the change. The number of that task can then differ between devices; agents use task IDs, which never change.
• Active runs: if both devices have an active run on the same task, the incoming one is skipped and listed as a conflict.

Command reference

istok export:

istok import FILE:

FILE can be - to read the export from standard input.