Commands — shuhari

init

shuhari init [<repo> | --no-repo] [flags]

Changes: The machine config, after you confirm. Clones of new tool-managed sources.
Lock: Yes. It also recovers an interrupted import first.

On a new machine, init asks where your skills are. Press Enter if you have none yet: it then writes a config with no sources. With a repository, it:

Searches it for SKILL.md directories, and proposes one skill pattern per parent directory.
For a working-copy source, proposes an import directory.
Proposes each git submodule as a tool-managed source, pinned to the commit that the repository records.
Adds an install choice for each owned link that exists today, so the next apply removes nothing that works now.
Shows every change and the plan of the next apply, and asks before it writes.
Prints the summary, and offers doctor --fix when an entry needs attention.

init never runs apply. Links change only when you run apply or sync.

On a machine with a config, init keeps the machine name, targets, install choices, excludes and local declarations. It asks only for new information. It also converts a config in the shuhari 1.0 format, which release 0.2.0 uses (one with a [catalog] table), in the same run.

Flags

Every question has a flag. Without a terminal, a question that no flag answers stops init with exit code 2 and names the flag.

Flag	Answers
`<repo>`	Where your skills are: a git URL or a local path. A URL becomes a tool-managed source. A local path must be a git repository, and becomes a working-copy source.
`--no-repo`	You have no skills repository yet.
`--name <source>`	The source name, when the default is taken or not valid.
`--machine <name>`	The machine name. The default comes from the system's display name.
`--skills <pattern>`	The skill patterns, instead of the proposed ones. Repeat for each pattern.
`--import-dir <dir>`, `--no-import-dir`	The import directory, or none.
`--submodules all\|none\|<names>`	Which proposed submodule sources to add.
`--submodule-name <path>=<name>`	The source name for one submodule. Repeat for each.
`--adopt-existing exact\|none`	Whether to add install choices for existing links. The default is `exact`.
`--yes`	Accept every proposal that no other flag answered, and the final confirmation.

Check

These commands change nothing.

shuhari scan

Lists every entry in targets, sources and scan_roots, with its state, diagnostics and summary group.

shuhari doctor

Prints the summary, then checks git, the machine config, each source and target, the entries of each target, existing links, the import destination, the import journal and the install choices. Under each problem, a help: line says what to do.

shuhari plan

Shows what apply would do.

shuhari status

For each source: clone path, HEAD, pin state, uncommitted changes, and commits behind or no remote. It uses the last fetched refs.

shuhari outdated

Lists pinned sources whose last-fetched upstream HEAD differs from their rev.

doctor --fix

shuhari doctor --fix

Changes: What each answer does: the machine config, a source, a target.
Lock: Yes. It needs a terminal.

It asks about each problem it can fix, one at a time. Before each question it checks again, so each question reflects the earlier fixes.

~/.claude/skills/draft-skill: [i]mport to agent-skills, keep [w]ip, keep [m]achine, [s]kip?
claude/rust-style -> ~/Projects/agent-skills/personal/rust-style: [a]dd agent-skills:rust-style to claude, [s]kip?

A failed fix is reported, and --fix continues with the next problem.

Choose

These commands change the machine config only. Run apply afterwards to change the links.

shuhari add <selector> --to <target>

Adds an install choice.

shuhari remove <selector> --from <target>

Removes the install-choice entries whose selector text equals <selector>, for that target. Then prints the skills that other rules still select for that target.

shuhari exclude <source:skill> [--from <target>]

Excludes one skill, everywhere or for one target.

shuhari keep <path> --wip | --machine

Declares a skill directory local on purpose. --wip accepts --review-after <YYYY-MM-DD>, and both accept --note <text>.

Change

shuhari apply

Changes: Owned links in every target.

Makes the owned links in every target match the install choices.

shuhari sync

Changes: Source clones, then owned links.

Updates every source, then runs apply. A source without git is not fetched.

shuhari bump <source>

Changes: The source's rev in the machine config.

Writes the newest upstream commit, as a full commit ID, into rev. Every other line of the file stays as it is. It refuses a source without git.

shuhari import <path> --to <source>

Changes: The source, the machine config and the target.

Copies one unmanaged skill directory into a source and replaces the original with a link. The path must be a directory directly inside a target. The source must be a working-copy source with an import_dir, and that directory must already exist.

Output and exit codes

Every command accepts --json: a command that completes prints one JSON object on stdout. A command that fails with exit code 2 or 3 prints plain text on stderr instead: an error: line, indented context, and help: lines that say what to do next.

error: the machine config uses the shuhari 1.0 format
  config: ~/.config/shuhari/config.toml
help: run `shuhari init` to convert it

Code	Meaning
0	Everything is done.
1	Partly done, and each problem is listed. For example: a failed `doctor` check, a declined `init`, a failed source update or link action, or an unmatched selector.
2	Configuration or usage error. The command made no changes, except that `init` may have cloned sources, which it lists as `clones kept`.
3	An interrupted import was recovered, and the command could not continue. The report lists each recovery step and why the command stopped.