Shirone provides a dedicated suite of CLI commands engineered for content separation. From external drafting to zero-disk memory validation, and bi-directional synchronization to safe snapshot resets, everything is executable via intuitive commands.

---

CLI Command Quick Reference

Command	Purpose	Typical Use Case	Disk Mutation
pnpm content:sync Frequent	Single full or incremental sync	Pre-preview sync or CI build content materialization	Writes to theme workspace
pnpm content:watch Frequent	Live incremental file watcher	External editor drafting with live browser preview	Auto writes on file save
pnpm content:validate Safety Check	In-memory schema & type validation	Fast syntax and typo diagnosis after editing YAML	In-memory check, zero disk writes
pnpm content:status Inspection	Repository and diff inspection	Check content source, branch, commit SHA, and uncommitted diffs	Read-only inspection
pnpm content:export Export	Reverse config export	Export modified YAML settings back into content repository	Writes to content repo
pnpm content:clean Snapshot Reset	Clean reset with auto backup	Restore clean theme workspace with automatic snapshot backup	Cleans local cache
pnpm content:eject One-Time Eject	One-click decoupling eject	Upgrade monolithic repository to decoupled dual repositories	Generates standalone repo

---

1. Single Sync: content:sync Core

content:sync

# 1. Incremental sync (materializes external content and compiles TS config overlay)
pnpm content:sync

# 2. Dry-run mode (previews changes without writing to disk)
pnpm content:sync --dry-run

Key Mechanics

• Automatic Content Source Detection: Checks CONTENT_DIR first, falling back to CONTENT_REPO_URL for remote Git cloning;
• Smart Incremental Diffing: Only copies changed files to eliminate unnecessary disk I/O;
• Automated Config Compilation: Compiles YAML files into typed src/user/user-config.ts bridge module.

---

2. Live Watch Mode: content:watch Recommended for Writing

content:watch

pnpm content:watch

Key Mechanics

• Millisecond-level debounced watcher syncing only modified files;
• Modifying any config/*.yaml automatically recompiles TypeScript bridge and triggers hot module replacement;
• Pairs with pnpm dev running in a companion terminal window.

---

3. In-Memory Validation: content:validate Zero Disk Writes

content:validate

pnpm content:validate

Key Mechanics

• Pure In-Memory Validation: Parses YAML, validates schemas, and checks TypeScript types in memory;
• Zero Disk Writes: Never writes temporary files to disk;
• Intelligent Typo Suggestions: Outputs line numbers and suggests correct property names for misspelled keys.

Recommended Before Committing

Run pnpm content:validate before pushing commits to catch YAML formatting or typo mistakes early.

---

4. Status Inspection: content:status

content:status

pnpm content:status

# Inspect remote Git connection and latest commit:
pnpm content:status --remote

---

5. Reverse Config Export: content:export

content:export

pnpm content:export          # Dry run: prints export plan
pnpm content:export --yes    # Execute export

Key Mechanics

• Minimal Overlay Export: Only exports keys differing from theme defaults, avoiding hardcoded default bloat;
• Protects Future Upgrades: Unmodified keys inherit upstream improvements automatically.

---

6. Safe Reset: content:clean

content:clean

pnpm content:clean          # Dry run: prints clean plan
pnpm content:clean --yes    # Execute clean

Snapshot Backup & Recovery

• Automatic Snapshot Backup: Automatically archives current local content to .content-backup/clean-<timestamp>/ before removal;
• Reset Theme Workspace: Cleans synced files and restores default demo content;
• Source Repository Untouched: External content repository remains completely unaffected.

Restoring Snapshot Backup

To restore workspace state from backup:

Windows (PowerShell)

Copy-Item -Recurse -Force .\.content-backup\clean-<timestamp>\* .

Linux / macOS (Bash)

cp -a .content-backup/clean-<timestamp>/. .

---

Manifest & Environment Precedence

Manifest File: shirone.content.json

shirone.content.json

{
  "schemaVersion": 1,
  "source": {
    "type": "path",
    "path": "../shirone-content"
  },
  "mounts": {
    "content": "src/content",
    "data": "src/data",
    "assets": "src/assets",
    "public": "public"
  },
  "keep": ["src/data/my-special-data.ts"],
  "prune": true
}

Environment Precedence

Precedence order: Process Env > .env.local > .env > shirone.content.json.

Variable	Description
CONTENT_DIR	Local content repository path
CONTENT_REPO_URL	Remote Git repository URL
CONTENT_REPO_REF	Target branch, tag, or commit SHA (default: main)
SHIRONE_CONTENT_SYNC	Set to 0 or false to disable sync and return to monolithic mode
CONTENT_SYNC_PULL	Set to false to reuse local cache without network pull

Expand to View Advanced CLI Flags

• --dry-run: Supported by mutating commands; prints execution plan without modifying disk;
• --verbose: Outputs per-file timing, MD5, and mtime comparison details;
• --force: Overrides conflict checks and forces synchronization;
• --json: Emits machine-readable JSON output for CI pipeline parsing.

---

Next Steps

• Head to Config Overlay Principles: Understand minimal overlay rules, object merging, and array replacements

Copyright

Copyright Ownership:matsuzaka-yuki

License under:Attribution 4.0 International (CC-BY-4.0)

Contributors: matsuzaka-yuki, Dawn6666666

Previous pageLocal Preview & Debugging

Next pageConfiguration Overlay