Skip to main content

Commands

CommandDoes
addFetch if needed, then write a bundle into the project
listList cached bundles (--source <source> to filter)
statusDesired state vs. what's written
remove [source] [bundle]Delete a bundle's managed files (--all for every one)
applyWrite all wanted bundles into this worktree
check [bundle]Report upstream updates, read-only
update [bundle]Move bundles to the latest upstream revision
syncgit pull --ff-only, with shadows suspended and refreshed
shadow--suspend or --refresh tracked shadows by hand
resetRemove everything Skul manages here

Common flags​

FlagApplies toEffect
-n, --dry-runmutating commandsPreview, change nothing
-y, --yesadd remove apply update resetApprove overwrite and removal prompts
-j, --jsonlist status check remove resetMachine-readable output
-g, --globaladd remove apply update status resetOperate on ~ tool config instead of the project

Mutating commands print { "output": "…", "warnings": [] } under --json. Set SKUL_NO_TUI=1 to turn off every interactive prompt, which is what scripts and agents should do.

add​

skul add [options] [source] [bundle]

source is github.com/owner/repo, owner/repo, an SSH URL such as git@github.com:owner/repo, or npm:@scope/package. Omit it to re-apply a uniquely named cached bundle without network. Omit bundle for a single-bundle repo, or to get a picker.

OptionEffect
-a, --agent <id>Target one tool; repeat for more. Without it, Skul asks which of the bundle's tools to target, and SKUL_NO_TUI=1 fails if there's more than one.
--ref <selector>Track a branch, tag, or commit instead of HEAD (npm: a version or dist-tag). Remembered by apply.
--include <item>Install only one item; repeat for more: skills/<name>, commands/<name>, agents/<name>, root-instruction, mcp
--select-itemsPick items interactively
--allEvery bundle from the source
-s, --sshClone over SSH. git@ URLs imply it. Remembered by apply.
--root-instruction-mode <mode>append (default) or replace
--disable-model-invocationMake every skill manual-only: the tool runs it only when you ask
skul add sjquant/ghosts writing --ref main
skul add writing --agent codex --include skills/rewrite
skul add npm:@you/react-skills@1.2.0 # your own package

If SSH auth fails, Skul prints the HTTPS equivalent.

Environment​

VariableEffect
SKUL_NO_TUI1 disables prompts; operations that need confirmation fail instead
SKUL_NPM_REGISTRYRegistry for npm: sources (then npm_config_registry, then npmjs.org)
SKUL_NPM_TOKENBearer token, sent only to that registry's origin

Staying current​

skul check shows what changed upstream; skul update applies it. A dist-tag like latest is followed; an exact version is pinned; semver ranges aren't supported.

Use skul update --global [bundle] to refresh globally installed bundles without a Git project. Saved tool and item selections are preserved; --dry-run previews changes.

For tracked AGENTS.md / CLAUDE.md, use skul sync for pulls. See How it stays out of Git.