SD-Linker

SD-Linker creates and removes symbolic links to Stable Diffusion model files; it does not copy or modify the model files themselves. It targets GNU/Linux.

Requirements

• PHP 8.3 or later
• Composer
• PHP PDO with the SQLite driver (pdo_sqlite)

Install

git clone https://github.com/froggie3/Stable-Diffusion-Checkpoint-Linker.git
cd Stable-Diffusion-Checkpoint-Linker
composer install
echo "export PATH=\"$(pwd)/bin:\$PATH\"" >> ~/.bashrc

The PATH line takes effect in new shells; run source ~/.bashrc to apply it to the current one. After that, the examples below run as linker; from the checkout root you can also run ./bin/linker without any PATH change.

The first successful operation creates the management database at data/links.sqlite by default when needed. Keep this file: it records which links SD-Linker manages. The data/ directory is ignored by Git.

Application settings are optional. To customize the configuration directory or database location, copy setting.example.ini to setting.ini in the checkout root and edit it. setting.ini is ignored by Git:

configuration_dir = "config"
database_path = "data/links.sqlite"

Both settings default to the values shown when omitted or when setting.ini is absent. Unknown settings, empty paths, and invalid INI are errors. Relative paths are resolved against the checkout root, regardless of the current working directory; absolute paths are also supported. Paths are literal, with no shell expansion. Changing the database path does not move existing records: copy the existing database to the new location if you want to retain them. Keep custom database files out of Git.

Agent skill

The modelop skill provides instructions for using SD-Linker from an agent. Install it with npx skills:

npx skills add froggie3/Stable-Diffusion-Checkpoint-Linker --skill modelop

The interactive command lets you choose the installation target. To install it into a Codex project explicitly, use:

npx skills add froggie3/Stable-Diffusion-Checkpoint-Linker --skill modelop --agent codex

Add -g for a global installation, for example npx skills add froggie3/Stable-Diffusion-Checkpoint-Linker --skill modelop -g. Use --list to inspect the skills published by this repository; from a local checkout, validate discovery with npx skills add . --list.

This installs skill instructions only. It does not install SD-Linker, PHP, or Composer; set up the project separately using the Install instructions above. The current npx skills CLI requires Node.js 22.20 or later.

Configure and run

Copy config/example.yaml, then edit the copy for your model and destination directories. The programs read YAML from standard input:

linker sync < /path/to/config.yaml
linker clear < /path/to/config.yaml

Use linker list to discover local configuration files under the configured configuration_dir (default config):

linker list

It recursively prints absolute paths to .yaml and .yml files (case-insensitive extensions), one per line, sorted lexically, without following directory symlinks or validating YAML. An empty directory produces no output; a missing or unreadable directory is an error. Listing does not read stdin or access the database.

Alternatively, pass the configuration file as a positional argument. When a file is supplied, standard input is ignored; options can appear before or after the file. Use -- before a file name that begins with -:

linker sync --dry-run /path/to/config.yaml
linker clear /path/to/config.yaml --verbose
linker sync -- -config.yaml

Use edit to open a configuration file without validating its YAML, reading standard input, accessing the management database, or running a sync:

linker edit /path/to/config.yaml
linker edit /path/to/config.yaml /usr/bin/code --wait

When no editor is given, VISUAL is used before EDITOR; either environment value is treated as a shell command. An editor supplied on the command line is executed directly without a shell. In both cases the config path is appended as the editor's final argument. linker edit --help shows the details.

sync creates or updates the selected links. clear removes links that the management database confirms belong to SD-Linker and that are described by the selected configuration. It does not search for links omitted from the configuration.

Both commands accept --help, --dry-run, and --verbose (or -v) for successful-operation details. The repeatable --category CATEGORY option limits an operation to categories already named in that configuration's lookupKeys list. For example:

linker sync --dry-run --category checkpoint < /path/to/config.yaml
linker clear --category checkpoint --category lora < /path/to/config.yaml

A category outside lookupKeys is an error. --dry-run performs configuration and operation checks and reports the planned work without changing links or the management database.

Run linker --help for the command list, or linker <command> --help for the full command reference.

Configuration and command reference

The configuration is YAML parsed by Symfony YAML 6.4. Paths are literal: ~, environment variables, and glob patterns are not expanded. destination and baseDirectory paths must be absolute. weightsList and ignoreList values are relative paths below baseDirectory and the category destination; entries containing .. are rejected. Quote paths and filenames when YAML could interpret them as another type.

See linker sync --help or linker clear --help for the full key schema, defaults, selection behavior, safety rules, output streams, and exit codes. Help prints without reading standard input or opening the database.

lookupKeys:
  - checkpoint

destination:
  checkpoint: /srv/stable-diffusion/models/Stable-diffusion

source:
  checkpoint:
    - meta:
        enabled: true
      baseDirectory: /srv/models/checkpoints
      weightsList:
        - example.safetensors
      ignoreList: []

An enabled group's weightsList entries are kept linked by sync. An enabled group's ignoreList entries are removal candidates during sync; a disabled group's weightsList entries are also removal candidates. clear considers both lists for enabled and disabled groups. An omitted ignoreList is empty.

Development

Run the test suite with:

composer test

Tests use temporary files and isolated databases. Run the project checks with:

composer check

Use composer lint for PHPStan and PHP syntax checks, composer format:check to see formatting differences, and composer format to apply the configured formatter.