Work with projects

Projects track which templates ran, the revision used, and the settings that were supplied. The commands below cover the full lifecycle.

Create a project

skaff project new my-service fastapi \
  --repo github:timonteutelink/example-templates \
  --settings ./settings.json   # optional inline JSON or path

If --settings is omitted, Skaff prompts for values derived from the template’s Zod schema. When the command finishes it opens a diff for review. Accept the patch to write files to disk.

Useful helpers:

• skaff project from-settings <path> replays a stored templateSettings.json.
• skaff project ls --format table lists all Skaff projects in configured search paths.
• skaff project show prints the active template tree for the current project.

Add or edit subtemplates

Subtemplates let you add optional modules or repeatable slices later in the project lifecycle.

skaff project add-subtemplate <parentId> <templateName> <subtemplateName> \
  --settings ./feature.json

Retrieve instance IDs from templateSettings.json. To modify an instance, run skaff project modify <instanceId> or prepare a diff with skaff project diff prepare-modification <instanceId>.

Prepare updates

Keep projects aligned with upstream template changes by rendering a diff against a newer revision:

skaff project update main            # branch, tag, or commit SHA
# or for manual control
diffHash=$(skaff project diff prepare-update main --format json | jq -r '.diffHash')
skaff project diff apply "$diffHash"

Resolve conflicts with your normal Git workflow. Skaff only touches files that belong to the template instance being updated.