Skip to content

CliReference

Jump to bottom
yCENzh edited this page Sep 19, 2026 · 1 revision

CLI reference

npx shirones <command>

Every command starts by printing the package-manager contract and a link to the repository, then does its work.

Shirone CLI

  init                 Scaffold the project — or report drift on an existing one
  init --update        Restore missing files and refresh the scaffold (never overwrites your files)
  init --force         Replace template files after backing up the previous copy
  info                 Detailed status and drift report
  help                 Show this message

init

Two different jobs depending on whether the project already exists.

In an empty directory, it scaffolds everything: package.json, pnpm-workspace.yaml, astro.config.mjs, tsconfig.json, src/content.config.ts, the shirones/ tree with all 33 config modules and the example content, and public/. Then it installs.

In an existing project, it changes nothing. It reports drift and exits. That is the safe default — running init out of habit will not clobber your work.

Existing files are skipped with a note rather than overwritten:

  ✓ shirones/config/siteConfig.ts already exists (use --force to overwrite)

init --update

Adds what is missing and refreshes what the theme owns, without touching what you wrote.

npx shirones init --update    # or -u

Use it after upgrading the package. It restores config modules the theme added, refreshes the project-level scaffold files, and leaves your content and your edits alone.

The rule it follows: the theme only adds. Anything already on disk is kept, even if the theme's version has changed. That is what makes it safe to run repeatedly, and it is also why it will not fix a config module you edited long ago and have since fallen behind — for that you need --force, or a manual merge.

init --force

Replaces the template trees and backs up what was there.

npx shirones init --force    # or -f

Before replacing anything, the previous files and directories are moved to .shirones-backup/:

  ✓ shirones replaced (--force), kept a copy at .shirones-backup/shirones
  ✓ public replaced (--force), kept a copy at .shirones-backup/public
  ✓ root files (8 added, 8 previous copies backed up)
  ✓ src/content.config.ts replaced (--force), kept a copy at .shirones-backup/src/content.config.ts
  ✓ astro.config.mjs already wires the theme in — replaced with the template (--force),
    kept a copy at .shirones-backup/astro.config.mjs

.shirones-backup/ is a complete tree, not a diff. Recover your posts, config and assets from it and then delete it. Nothing prunes it automatically, and a second --force overwrites the previous backup.

This is the destructive command. It is the right tool when the theme's config modules have moved on and merging by hand is more work than re-applying your edits to a fresh copy — but read the log, because your content directory is inside what gets replaced.

info

Read-only. Reports the installed package, Node compatibility, provenance, project state and drift.

npx shirones info

Covers:

  • Node — your version against the package's requirement
  • Package manager — detected, and whether the project is pinned
  • Provenance — the package version, and the upstream theme commit it was built from
  • Paths — resolved config, data and content directories
  • Content — entry counts per collection
  • Inventory — how many components, layouts, config modules and data modules the theme exposes
  • Drift — see below

On a project that has not been scaffolded, info says so and stops:

Run `npx shirones init` to scaffold this project.

Drift

Both init (on an existing project) and info report drift. Four categories:

Category Meaning
missing config a config module the theme has that you do not
stale files kept a file you have that the theme no longer ships
changed config a config module where the theme added or changed fields
missing root a project-level scaffold file that is absent 
Drift
  status           3 difference(s)
    missing config
      - shirones/config/seriesConfig.ts
    changed config
      - shirones/config/siteConfig.ts
    missing root
      - tsconfig.json
    Run `npx shirones init --update` to restore safe missing files.

status reads up to date when there is nothing to report.

Missing files and missing root files are restored by --update. Changed config is not — the CLI will not merge TypeScript for you. It tells you which modules changed so you can diff them against the theme's current version in node_modules/shirones/src/config/.

Exit codes

init and info exit zero on success. An unknown command prints the help and exits 1.

Next

Clone this wiki locally