Commands
| Command | Does |
|---|---|
add | Fetch if needed, then write a bundle into the project |
list | List cached bundles (--source <source> to filter) |
status | Desired state vs. what's written |
remove [source] [bundle] | Delete a bundle's managed files (--all for every one) |
apply | Write all wanted bundles into this worktree |
check [bundle] | Report upstream updates, read-only |
update [bundle] | Move bundles to the latest upstream revision |
sync | git pull --ff-only, with shadows suspended and refreshed |
shadow | --suspend or --refresh tracked shadows by hand |
reset | Remove everything Skul manages here |
Common flags
| Flag | Applies to | Effect |
|---|---|---|
-n, --dry-run | mutating commands | Preview, change nothing |
-y, --yes | add remove apply update reset | Approve overwrite and removal prompts |
-j, --json | list status check remove reset | Machine-readable output |
-g, --global | add remove apply update status reset | Operate 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.
| Option | Effect |
|---|---|
-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-items | Pick items interactively |
--all | Every bundle from the source |
-s, --ssh | Clone over SSH. git@ URLs imply it. Remembered by apply. |
--root-instruction-mode <mode> | append (default) or replace |
--disable-model-invocation | Make 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
| Variable | Effect |
|---|---|
SKUL_NO_TUI | 1 disables prompts; operations that need confirmation fail instead |
SKUL_NPM_REGISTRY | Registry for npm: sources (then npm_config_registry, then npmjs.org) |
SKUL_NPM_TOKEN | Bearer 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.