Configuration Format

SpaceLauncher configuration exports are JSON files you can read, diff, copy to another Mac, or process with your own scripts.

This page is a trust-oriented reference, not a complete API specification. The format can evolve, so tools should preserve unknown fields when possible.

Export Types

SpaceLauncher writes two JSON package types.

.slbindings exports key bindings only:

• format: name.guoc.SpaceLauncher.key-bindings
• version: currently 1
• keyBindings: an array of key binding rules

.slbackup exports a full app backup:

• format: name.guoc.SpaceLauncher.backup
• version: currently 1
• configuration: the full AppConfiguration

The package version is different from the app configuration schemaVersion. The current AppConfiguration schema version is 2.

Full Configuration

A full AppConfiguration contains:

• schemaVersion
• commandTrees
• bindings
• disabledApplications
• suggestedDisabledApplicationPaths

commandTrees is the current persisted structure. bindings is also encoded for compatibility with tools and older import paths.

Key Binding Rule

Each rule is a FlatKeysAndActionRow with these main fields:

• id: UUID
• enabled: boolean
• applicationScope: either allBut(paths) or only(paths)
• keys: trigger key code sequence
• action: action payload, with optional human description stored as description
• leaderKey: hold or tap leader definition
• holdContinuationIndexAfterAction: optional continuation setting for hold leaders

applicationScope has two shapes:

{
  "allBut": {
    "paths": []
  }
}

{
  "only": {
    "paths": [
      "/Applications/TextEdit.app"
    ]
  }
}

Example

This .slbindings example contains one binding: hold Space, then press F and D, to open the Downloads folder.

{
  "appVersion": "3.0.0 (300)",
  "exportedAt": "2026-06-07T12:00:00Z",
  "format": "name.guoc.SpaceLauncher.key-bindings",
  "keyBindings": [
    {
      "action": {
        "description": "Open Downloads",
        "openFolder": {
          "applicationPath": null,
          "folderPath": "~/Downloads"
        }
      },
      "applicationScope": {
        "allBut": {
          "paths": []
        }
      },
      "enabled": true,
      "id": "11111111-2222-4333-8444-555555555555",
      "keys": [
        3,
        2
      ],
      "leaderKey": {
        "hold": {
          "info": {
            "keepsTapFunction": true,
            "keyCode": 49
          }
        }
      }
    }
  ],
  "version": 1
}

Key code 49 is Space on the standard Mac keyboard layout. Key codes 3 and 2 are F and D.

Import Behavior

Key binding imports can merge new rules into your current setup or replace all current key bindings. When merging, SpaceLauncher checks for duplicate binding identity using leader key, trigger keys, and application scope.

Full backup restore is different: restoring a .slbackup replaces the app configuration. It is meant for backup recovery, not partial merge.

Why This Matters

The format is human-readable and scriptable. You can inspect a binding, compare changes in a diff, migrate a setup between machines, or generate rules with your own tooling. SpaceLauncher also keeps local rolling, timestamped backups of the saved configuration, and warns about shortcut conflicts before saving.