# The notebook command

Canonical: https://godspeedmissioncontrol.com/guide/notebook-command

`godspeed.mjs` is the notebook's maintenance program. **Settings**, **Recovery** in the notebook saves and checks backups with a click; this program does the rest from a terminal. You start it with Node, the program that runs the notebook. It needs two settings: `GODSPEED_WORKSPACE`, your mission control folder, and `GODSPEED_MEDIA_ROOT`, where files attached to notes are kept. Open a terminal (PowerShell on Windows, Terminal on a Mac) and run the block for your installation first.

## Get ready

### Windows

In PowerShell:

```powershell
$program = "$env:LOCALAPPDATA\Godspeed Mission Control"
$state = "$env:LOCALAPPDATA\Godspeed Mission Control State"
if (-not (Test-Path "$state\installation.json")) {
  $program = "$env:LOCALAPPDATA\Godspeed Mission Control Full Alpha"
  $state = "$env:LOCALAPPDATA\Godspeed Mission Control Full Alpha State"
}
$app = "$program\payload"
$node = "$app\runtime\node.exe"
$notebook = "$app\kit\notebook\bin\godspeed.mjs"
$env:GODSPEED_WORKSPACE = "$env:USERPROFILE\godspeed-v2"
$env:GODSPEED_MEDIA_ROOT = "$state\media"
```

The lines with `if` choose the folders. A Windows install made before 2.0.0-beta.11 keeps its older folder names, which end in "Full Alpha" and "Full Alpha State", also after updating. These lines find them.

If you chose another folder during setup, put it in `GODSPEED_WORKSPACE`. Run a command as `& $node $notebook validate`. For `restore`, use [Git Bash](/guide/glossary#git-bash) instead:

```bash
PROGRAM="$LOCALAPPDATA/Godspeed Mission Control"
STATE="$LOCALAPPDATA/Godspeed Mission Control State"
if [ ! -f "$STATE/installation.json" ]; then
  PROGRAM="$LOCALAPPDATA/Godspeed Mission Control Full Alpha"
  STATE="$LOCALAPPDATA/Godspeed Mission Control Full Alpha State"
fi
APP="$PROGRAM/payload"
NODE="$APP/runtime/node.exe"
NOTEBOOK="$APP/kit/notebook/bin/godspeed.mjs"
export GODSPEED_WORKSPACE="$USERPROFILE/godspeed-v2"
export GODSPEED_MEDIA_ROOT="$STATE/media"
```

### Mac and Linux

On a Mac, a Linux computer or a server without Docker:

```bash
export GODSPEED_WORKSPACE="$HOME/godspeed-v2"
RUNTIME="$GODSPEED_WORKSPACE/.godspeed/integrated-runtime"
export GODSPEED_MEDIA_ROOT="$RUNTIME/media"
NODE="$(ls -d "$RUNTIME"/runtime/node-v*/bin/node | tail -n 1)"
NOTEBOOK="$RUNTIME/versions/$(cat "$RUNTIME/version")/notebook/bin/godspeed.mjs"
```

If you installed somewhere else, put that folder in `GODSPEED_WORKSPACE`. If the `NODE` line prints "No such file or directory", write `NODE=node` instead. Run a command as `"$NODE" "$NOTEBOOK" validate`.

### The one-line server

On the one-line server the program runs inside the container, with both settings already set. As root:

```bash
cd /opt/godspeed-mission-control
docker compose exec -u hermes godspeed node /opt/godspeed/kit/notebook/bin/godspeed.mjs validate
```

[Server commands](/guide/server-commands) has more.

## Commands

The examples use the Mac and Linux names. In PowerShell, write `& $node $notebook` for `"$NODE" "$NOTEBOOK"`. Every command also prints "ExperimentalWarning: SQLite is an experimental feature", a harmless note from Node that never ends up in a file you save with `>`.

### validate

Checks every record of the notebook, such as a note, a person or a fact, and lists the problems.

```bash
"$NODE" "$NOTEBOOK" validate
```

A healthy notebook answers:

```text
{
  "problems": []
}
```

### export

Saves every notebook record in one JSON file, with `"format": 1` and a list called `records`. Your media files are not in it, and neither are the keys other apps use to reach your notebook.

```bash
"$NODE" "$NOTEBOOK" export notebook-export.json
```

```text
{
  "exported": 412,
  "file": "/home/you/notebook-export.json"
}
```

It never writes over a file: "There is already a file at" means you should choose a new name. Without a file name it writes the same JSON to the screen, so `export > notebook-export.json` works too, also in Windows PowerShell.

To read your notebook elsewhere you need no export: the `notebook/` folder holds every page as a Markdown file.

### backup

Copies your notebook with its history, the readable files of your mission control and your media into a new folder, with a checksum for every file in `backup.json`.

```bash
"$NODE" "$NOTEBOOK" backup "$HOME/godspeed-backups/2026-10-17"
```

The folder must not exist yet. On success it prints the folder's path. Keys, passwords, program files and hidden folders such as `.godspeed` are left out.

- "Backup destination already exists": choose a new folder name.
- "Creating a backup needs" a size "free, but only" a smaller size "is available": free some disk space, or choose a drive with more.
- "Archive cannot follow symbolic links": a folder it copies, such as `skills/`, holds a link. Replace the link with the real files.

The nightly backups sit in `.godspeed/backups` in your folder ([Back up and restore](/guide/back-up)).

With `--before-update` it makes the smaller copy the installers make before an update: only what an update can change, never `work/`. When your folder is a Git repository, it holds only the files that differ from your last commit. It keeps that commit in Git, so the copy can be restored.

```bash
"$NODE" "$NOTEBOOK" backup "$HOME/godspeed-backups/before-update" --before-update
```

### restore

Puts a backup into an empty mission control folder and an empty media folder. It first checks every file against its checksum, and it never writes over a notebook that has content.

```bash
mkdir -p "$HOME/restored/workspace" "$HOME/restored/media"
GODSPEED_WORKSPACE="$HOME/restored/workspace" GODSPEED_MEDIA_ROOT="$HOME/restored/media" "$NODE" "$NOTEBOOK" restore "$HOME/godspeed-backups/2026-10-17"
```

On Windows, run these lines in Git Bash. On success it prints how many records it restored. No command makes your installation run on the restored folder; [Back up and restore](/guide/back-up) shows how to carry on.

- "Restore requires an empty workspace", "... empty durable state" or "... empty media storage": use new, empty folders.
- "Backup integrity mismatch": a file in the backup changed or is damaged.
- "is not a backup: it has no backup.json": the folder you named is not a backup. Name a folder a backup was saved in, such as one in `.godspeed/backups`.
- "that commit is not there": the copy was made before an update, and the rest of it is in the history of your folder's Git repository. Run the restore on the computer the copy was made on, or add `--repository` and the folder of a clone that has the commit.

### import

Brings the records of an export file into the notebook in the folder that `GODSPEED_WORKSPACE` names: a new, empty folder, or a notebook you already use.

```bash
"$NODE" "$NOTEBOOK" import notebook-export.json
```

```text
{
  "imported": 5,
  "unchanged": 407
}
```

It never writes over what your notebook has. A record that is already there and the same is counted as `unchanged`, so importing a notebook's own export changes nothing. A record your notebook holds in another version stays as it is, and the answer names it under `kept_as_they_are`. A starter record you never changed takes the version from the file. Run it again with the same file and nothing changes. It reads an export saved by Windows PowerShell too.

- "This file is not a notebook export": the file is not one the `export` command wrote, or it was damaged. Make a new export.
- "There is no file at": check the file's name and folder.

### prune-backups

Removes older copies of your notebook that the installers on Windows, a Mac and Linux save before each update, keeping the newest. It never touches nightly backups or one you named yourself. The installers run it after every update that worked.

```bash
"$NODE" "$NOTEBOOK" prune-backups "$RUNTIME/backups" --made <copy>
```

`<copy>` is the newest folder in there, which always stays. On Windows, in Git Bash, the folder is `"$STATE/backups"`. A wrong copy answers "Nothing was removed."

### sync folder

Lets the notebook travel in your folder's own Git repository, when you cloned the folder from a private GitHub repository. The installers run it when a computer joins a mission control already on GitHub.

```bash
"$NODE" "$NOTEBOOK" sync folder
```

When it worked, it answers `"enabled": true` and the repository's address. A new installation's folder has no copy on GitHub yet. There it refuses with "This folder's repository has no copy on GitHub yet (origin); connect one with Connect record sync in Settings". There, use **Connect record sync** in **Settings** instead ([Use it on two computers](/guide/several-devices)).

- "This repository is publicly readable. Choose a private repository for your knowledge"
- "Add these to the ignore file of the repository first:" with the folders to add to `.gitignore`.
- "This folder has no repository of its own": the folder is not a Git repository.

### assistant profiles and assistant select

When a computer joins your mission control through GitHub, the assistant's earlier conversations come along. `profiles` lists them, and `select` hands one to this computer's assistant before its first use.

```bash
"$NODE" "$NOTEBOOK" assistant profiles
"$NODE" "$NOTEBOOK" assistant select <profile id>
```

With nothing to choose from, `profiles` answers `[]`. Once the assistant has been used, `select` refuses with "Choose the restored assistant history before you first open the new assistant." On Windows, `select` stops with an error.

### workspace-move

Moves a Windows mission control folder to another place on the same computer. It works in three steps: a plan that changes nothing, the move, and an undo if you want the old place back. It keeps every copy: the old folder stays beside the new one, under a name ending in `.retained-` and a number. The old path keeps leading to the new folder, so shortcuts and settings that name it go on working. Links inside the folder, such as `.claude\skills`, move with it.

In PowerShell, after the lines under [Windows](#windows):

```powershell
$installation = "$state\installation.json"
& $node $notebook workspace-move plan D:\godspeed-v2 $installation > "$env:USERPROFILE\move-plan.json"
```

Read the plan, then stop the notebook and move:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$program\stop-notebook.ps1"
& $node $notebook workspace-move apply "$env:USERPROFILE\move-plan.json"
```

When the answer says `"state": "verified"`, start the notebook again, or sign out of Windows and back in:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$program\start-notebook.ps1"
```

The answer's `receipt_file` is the file an undo needs. To undo, set `GODSPEED_WORKSPACE` to the new folder, stop the notebook again and run `& $node $notebook workspace-move undo <receipt_file>`.

- "Choose an absent destination outside the current workspace": the new place must not exist yet and must not be inside the old one.
- "Stop only this installation’s notebook and assistant before its physical move": stop the notebook first.
- "The reviewed move plan changed": something in the folder changed since the plan. Make a new plan.
- "Your folder holds a linked folder or file that leads outside it" (or "leads nowhere"): remove or replace the link it names, then make a new plan.

This needs the `installation.json` the Windows installer keeps, so on a Mac or Linux it does not work.

### init

Sets up or updates the mission control folder. The installers run it on every install and update, and a server runs it at every container start. Running it again is safe.

```bash
"$NODE" "$NOTEBOOK" init
```

```text
{
  "initialized": true,
  "preservedExisting": true,
  "habitProgressUpgrades": 0
}
```

It copies missing starter files and installs or updates the skills that ship with Godspeed. A shipped skill you edited stays as you wrote it, and the newer version waits under **Review conflicting edits** in **Settings**. A shipped skill you deleted comes back.

A new installation's folder is a Git repository with nothing saved in it yet. There `init` saves everything once, as the first commit "Start my mission control" on the branch `main`, and its answer shows `"firstCommit"`. Keys, the search databases, photos and backups in `.godspeed` stay out of Git. A folder that already has commits is never touched.

### Other subcommands

The installers, the skills and the assistant use these:

- `food-table status` and `food-table install`: show or download the food table the food tracker uses.
- `memory search <words>`: searches the notebook's index.
- `record list`, `get`, `save`, `merge`, `remove`, `rename` and `display-name`: read or change one record.
- `world claim`, `world event` and `world close --dry-run`: add a fact or an event, or show which facts are no longer true.
- `coach`, `journal` and `charm`: pass a command on to the habits, journal and Charm Challenge programs.

With no command or an unknown one, it lists the commands, starting "Commands: init, record list/get/save/merge/remove/display-name". Without `GODSPEED_WORKSPACE` it stops with "Set GODSPEED_WORKSPACE to your mission control folder".