Skip to content

Getting Started ​

ziku has two roles: template author (setup) and template user (init). If someone else has already set up the template, skip to Step 2.

Step 1: Create the template (setup) — template author ​

ziku setup initializes a template repository by creating .ziku/ziku.jsonc. This file defines which file patterns ziku manages.

bash
# In your template repository
npx ziku setup

This creates .ziku/ziku.jsonc with default patterns. Edit it to match your needs:

jsonc
{
  "$schema": "https://raw.githubusercontent.com/tktcorporation/ziku/main/schema/ziku.json",
  "include": [
    ".claude/settings.json",
    ".claude/rules/*.md",
    ".claude/skills/**",
    ".mcp.json",
    ".devcontainer/**",
  ],
}

You can also set up a remote template repository:

bash
# Create a PR to add .ziku/ziku.jsonc to a remote repo
npx ziku setup --remote --from my-org/my-templates

By default, ziku looks for {your-org}/.ziku, then {your-org}/.github based on your git remote. If the repository doesn't exist, npx ziku will offer to create it interactively.

Step 2: Apply the template (init) — template user ​

ziku init (or just npx ziku) downloads the template and lets you select which directories to sync.

bash
# Auto-detect template from git remote
npx ziku

# Use a specific template
npx ziku --from my-org/my-templates

# Use a local directory as template (no GitHub needed)
npx ziku --from-dir ../my-template

ziku copies the matching files into your project and creates:

  • .ziku/ziku.jsonc — selected sync patterns (same format as the template)
  • .ziku/lock.json — template source + sync state (hashes, refs)

Step 3: Keep it in sync ​

bash
# Push local improvements back to the template
npx ziku push -m "Add new workflow"

# Pull latest template updates (includes new patterns)
npx ziku pull

# Check what's different
npx ziku diff

# Add file patterns to the sync whitelist
npx ziku track '.eslintrc.*'

push works with both GitHub (creates a PR) and local templates (copies files directly). pull also syncs new patterns added to the template's ziku.jsonc.

Released under the MIT License.