CLI Reference

Complete reference for all rolecraft commands, flags, and options.

Node.js API: rolecraft also exposes a programmatic API. See src/index.js or import { ... } from 'rolecraft'. All API functions return plain objects with no side-effects.

---

Commands

Command	Description
init [name]	Scaffold a new SKILL.md (--template, --list)
install <source>	Install a skill with security scan
bundle <sources...>	Install multiple skills from inline sources
bundle create [name]	Create a new bundle JSON file
use <source>	Preview a skill's files without installing
list	Show all installed skills
remove <slug>	Uninstall a skill
update <slug>	Re-install a skill to latest version
rollback <slug>	Restore a skill to previous version (from backup history)
setup [source]	Detect agents and optionally install a skill
search <query>	Search GitHub for skills (--skills-sh for skills.sh)
check	Check for available updates
ci	Re-install all skills from lockfile (CI mode)
verify	Check installed skill integrity via content hash
doctor	Run system health check
watch [slug]	Watch skills for changes and auto-sync
convert <source>	Convert between SKILL.md and .mdc formats
profile save/apply/list	Save, apply, and manage multi-agent profiles
mcp install/list/remove/update/check/search	Install, list, remove, update, check, and search MCP servers
agents-xml [--write]	Generate skills XML for AGENTS.md
completions bash|zsh|fish	Generate shell completion scripts
test <skill-path>	Test a skill quality with built-in assertions
diff <a> <b>	Compare two skills section-by-section
compose <a> <b> [<c>...]	Compose multiple skills into one
upgrade	Upgrade rolecraft to latest version
--help, -h	Show usage
--version, -v	Show version

---

Common flags

--verbose, --help and --version are accepted by every command. Every other flag is accepted only by the commands listed here — this table is generated from src/commands/spec.js, which is also what --help and the shell completions are generated from, so the three cannot drift.

Flag	Commands	Description
--agent	list	Filter by installed agent
--agents	init	Declare target agents
--all	install	Install to all locations
--all	mcp	Install to all supported agents
--all	test	Test all installed skills
--brief	diff	Show only a summary
--chain	compose	Override mode (last skill wins)
--context	diff	Lines of context around each change
--copy	install	Install as copy (default)
--deep	doctor	Run deep checks
--description	init	Set the skill description
--dry-run	install, bundle, remove, update, rollback, setup, watch, profile, mcp, upgrade, convert, compose	Preview without making changes
--force	compose	Overwrite existing output file
--frozen-lockfile	install	Fail if skill already installed
--global	install	Install to ~/.agents/skills/
--interactive	search, mcp	Choose and install from results
--json	list, search, doctor, agents, diff, compose, test	Output structured JSON
--list	install, setup	List available skills without installing
--list	use	List available skills without previewing
--list	rollback	Show available rollback versions
--list	init	List available templates
--min-score	test	Fail if score is below threshold
--name	mcp	Override server name
--name	compose	Set output skill name
--network	doctor	Run network checks
--no-color	diff, compose, test	Disable colored output
--no-emoji	test	Use ASCII fallback for emojis
--no-mcp	install, bundle	Skip MCP server installation
--npm	mcp	Search npm instead of GitHub
--only	test	Run specific checks
--output	convert	Write result to file
--output	compose	Write to file instead of stdout
--project	install	Install to ./.agents/skills/
--skill	install	Select skills by name
--skill	use	Preview skills by name
--skill	setup	Install skills by name
--skills-sh	search	Search skills.sh instead of GitHub
--symlink	install	Install as symlink instead of copy
--template	init	Scaffold from a named template
--write	agents-xml	Write skills XML to AGENTS.md
--yes	install	Non-interactive: accept all defaults
--yes	bundle, update, setup, search, profile, mcp	Skip confirmation
--<agent>	install	One flag per agent, e.g. --claude. See Agent-specific flags

ci takes no flags at all — it installs immediately and rejects anything else.

Flags take their value as a separate argument (--agent opencode), never as --agent=opencode. The = form is rejected with a hint rather than silently ignored.

---

Exit codes

Code	Meaning
0	Success — the command did what it said
1	Failure, including: a prompt was needed but stdin is not a terminal, an unknown flag, an unknown subcommand, a network error, or a skill that could not be found

If a command needs to ask a question and stdin is not a terminal, it fails with an actionable message rather than proceeding with a default. Pass the non-interactive flag for that command (--yes, --project, --all) to run it in a script.

Environment

Variable	Effect
NO_COLOR	Disable colored output (also honoured automatically when stdout is not a TTY)
FORCE_COLOR	Keep colored output even when stdout is piped

---

Agent-specific flags

Pass any of these to install, setup, or profile to target specific agents:

Flag	Agent	Skill directory
--agents	opencode	~/.agents/skills/
--claude	claude-code	~/.claude/skills/
--cursor	cursor	~/.cursor/skills/
--windsurf	windsurf	~/.codeium/windsurf/skills/
--devin	devin	./.devin/skills/
--codex	codex	~/.agents/skills/
--copilot	copilot	./.github/skills/
--aider	aider	~/.aider/skills/
--cline	cline	~/.cline/skills/
--gemini	gemini-cli	~/.gemini/skills/
--cody	cody	~/.cody/skills/
--continue	continue	~/.continue/skills/
--warp	warp	~/.agents/skills/
--codeium	codeium	~/.codeium/skills/
--fabric	fabric	~/.fabric/skills/
--goose	goose	~/.agents/skills/
--tabnine	tabnine	~/.tabnine/agent/skills/
--supermaven	supermaven	~/.supermaven/skills/
--pr-pilot	pr-pilot	~/.pr-pilot/skills/
--loom	loom	~/.loom/skills/
--roo	roo	~/.roo/skills/
--trae	trae	~/.trae/skills/
--hermes	hermes	~/.hermes/skills/
--kiro	kiro	~/.kiro/skills/
--augment	augment	~/.augment/skills/
--kilo	kilo	~/.kilo/skills/
--openhands	openhands	~/.agents/skills/
--junie	junie	~/.junie/skills/
--factory	factory	~/.factory/skills/
--command-code	command-code	~/.commandcode/skills/
--cortex	cortex	~/.snowflake/cortex/skills/
--mistral-vibe	mistral-vibe	~/.vibe/skills/
--qwen-code	qwen-code	~/.qwen/skills/
--openclaw	openclaw	~/.openclaw/skills/
--codebuddy	codebuddy	~/.codebuddy/skills/
--mux	mux	~/.mux/skills/
--pi	pi	~/.pi/agent/skills/
--autohand-code	autohand-code	~/.autohand/skills/
--rovo	rovo-dev	~/.rovodev/skills/
--firebender	firebender	~/.firebender/skills/
--bob	ibm-bob	~/.bob/skills/
--aider-desk	aider-desk	~/.aider-desk/skills/
--zap	zap	~/.zap/skills/
--codeep	codeep	~/.codeep/skills/
--kimi-code	kimi-code	~/.kimi-code/skills/
--zcode	zcode	~/.zcode/skills/
--astrbot	astrbot	~/.astrbot/data/skills/
--qoder-cn	qoder-cn	~/.qoder-cn/skills/
--trae-cn	trae-cn	~/.trae-cn/skills/
--zenflow	zenflow	~/.zenflow/skills/
--neovate	neovate	~/.neovate/skills/
--pochi	pochi	~/.pochi/skills/
--adal	adal	~/.adal/skills/
--droid	droid	~/.droid/skills/
--chatgpt	chatgpt	~/.agents/skills/
--codearts-agent	codearts-agent	~/.codeartsdoer/skills/
--universal	universal	~/.config/agents/skills/
--amp	amp	~/.config/agents/skills/
--antigravity	antigravity	~/.agents/skills/
--antigravity-cli	antigravity-cli	~/.agents/skills/
--deepagents	deep-agents	~/.agents/skills/
--dexto	dexto	~/.agents/skills/
--loaf	loaf	~/.agents/skills/
--replit	replit	./.agents/skills/
--zed	zed	~/.agents/skills/
--promptscript	promptscript	./agent/skills/
--code-arts-doer	code-arts-doer	~/.codeartsdoer/skills/
--code-maker	code-maker	~/.codemaker/skills/
--code-studio	code-studio	~/.codestudio/skills/
--crush	crush	~/.crush/skills/
--eve	eve	./agent/skills/
--forge	forge	./.forge/skills/
--inference-sh	inference-sh	~/.inferencesh/skills/
--jazz	jazz	~/.jazz/skills/
--iflow	iflow	~/.iflow/skills/
--kilo-code	kilo-code	~/.kilocode/skills/
--kode	kode	~/.kode/skills/
--lingma	lingma	~/.lingma/skills/
--mcp-jam	mcp-jam	~/.mcpjam/skills/
--moxby	moxby	~/.moxby/skills/
--ona	ona	~/.ona/skills/
--qoder	qoder	~/.qoder/skills/
--reasonix	reasonix	~/.reasonix/skills/
--terra-mind	terra-mind	~/.terramind/skills/
--tiny-cloud	tiny-cloud	~/.tinycloud/skills/
--zencoder	zencoder	~/.zencoder/skills/
--codebuddy	codebuddy	~/.codebuddy/skills/
(see full list for all 90 agents)

Combine multiple flags in one command:

rolecraft install ./my-skill --cursor --claude --devin --copilot

---

Subcommand detail

rolecraft init [name]

Scaffold a new skill:

rolecraft init my-skill                # creates ./my-skill/SKILL.md
rolecraft init                         # creates ./my-skill/SKILL.md (default: my-skill)
rolecraft init --list                  # list available templates
rolecraft init my-skill --template basic # scaffold from a specific template

Options:

Option	Description
--list	List available templates with descriptions
--template <name>	Scaffold from a named template (basic, code-review, git-workflow, testing, security, react)

See the init command docs for available templates and full examples.

rolecraft install <source>

Install a skill from any source:

rolecraft install ./path                             # local directory
rolecraft install owner/repo                         # GitHub shorthand
rolecraft install https://gitlab.com/org/project     # Git URL
rolecraft install git@github.com:owner/repo.git      # SSH URL
rolecraft install npm:package                        # npm package

Accepts: --yes, -y, --dry-run, --global, --project, --all, --symlink, --frozen-lockfile, --no-mcp, --list, --skill, agent flags.

rolecraft bundle <sources...>

rolecraft bundle owner/skill1 owner/skill2 ./local
rolecraft bundle bundle.json
rolecraft bundle bundle.txt
rolecraft bundle create [name]

Flags:

Flag	Description
--dry-run	Preview without installing
--no-mcp	Skip MCP server installation from skills

rolecraft use <source>

Preview without installing. Same source types as install.

rolecraft use ./my-skill         # show files
rolecraft use owner/repo         # from GitHub
rolecraft use ./my-skill | head -50  # pipe to pager

Flags:

Flag	Description
--list	List available skills from a source without previewing
--skill <names>	Preview specific skills by name (comma-separated)

rolecraft list

rolecraft list                  # all installed skills
rolecraft list --json            # machine-readable JSON output
rolecraft list --agent cursor    # only skills installed to cursor (-a alias)

rolecraft remove <slug>

rolecraft remove my-skill
rolecraft remove my-skill --dry-run

rolecraft update <slug>

Re-install from original source:

rolecraft update my-skill

rolecraft setup [<source>]

rolecraft setup                  # detect agents only
rolecraft setup ./my-skill       # detect + install
rolecraft setup owner/repo --yes

Flags:

Flag	Description
--yes, -y	Install all skills without prompt
--dry-run	Preview without installing
--list	List available skills from a source without installing
--skill <names>	Install specific skills by name (comma-separated)

rolecraft search <query>

rolecraft search code-review                  # GitHub search
rolecraft search code-review --interactive     # TUI picker
rolecraft search react --skills-sh             # skills.sh (experimental)

rolecraft check

No arguments. Checks all installed skills for newer versions.

rolecraft ci

Re-install all skills and MCP servers from lockfiles. Non-interactive by design — it takes no flags, and any flag (including --dry-run) is rejected rather than ignored, because ci writes to disk the moment it runs.

rolecraft verify

Verifies SHA256 content hashes of all installed skills.

rolecraft doctor

rolecraft doctor                # standard health check
rolecraft doctor --json         # JSON output for scripting
rolecraft doctor --network      # include GitHub connectivity test
rolecraft doctor --deep         # skill conflict detection

Runs comprehensive system health checks: Node.js version, platform info, Git/npm availability, agent directories, lockfile schema validation, disk usage, orphaned directory detection, skill integrity (hash + symlink), MCP server configuration, optional network connectivity (--network), and conflict detection (--deep).

rolecraft watch [<slug>]

rolecraft watch                 # watch all skills
rolecraft watch my-skill        # watch specific skill
rolecraft watch --dry-run       # preview what would be watched

rolecraft convert <source>

Converts between formats. Auto-detects direction:

rolecraft convert ./skill/SKILL.md     # → .mdc
rolecraft convert ./rule.mdc            # → SKILL.md
rolecraft convert ./dir/                # directory, auto-detects format
rolecraft convert ./dir/ --output ./out
rolecraft convert ./skill --dry-run

Flags:

Flag	Description
--dry-run	Preview without converting
--output <dir>	Output directory (default: current dir)

rolecraft profile

profile save <name>           # capture current config
profile apply <name>          # apply saved config
profile list                  # list all profiles
profile show <name>           # show profile details
profile diff <name>           # compare with current
profile edit <name>           # edit with $EDITOR
profile delete <name>         # remove profile
profile export <name>         # export as JSON
profile import <path>         # import from file/URL
profile link [name]           # link to project

Common flags: --yes/-y, --dry-run, --all, agent flags (--cursor, --claude, etc.)

rolecraft mcp

mcp install <source> [flags]    # install MCP server
mcp list                        # list all MCP servers
mcp search <query> [flags]      # search MCP servers (--npm, --interactive)
mcp check                       # check for MCP server updates
mcp update <name> [flags]       # update an MCP server
mcp remove <name> [flags]       # remove MCP server

Flags: --yes/-y, --dry-run, --name <name>, --all, agent flags (--cursor, --claude, etc.), --npm, --interactive (for search).

rolecraft agents-xml [--write]

Generates XML block for AGENTS.md. Use --write to auto-insert.

rolecraft completions bash|zsh|fish

rolecraft completions bash >> ~/.bashrc
rolecraft completions zsh >> ~/.zshrc
rolecraft completions fish >> ~/.config/fish/completions/rolecraft.fish

rolecraft test <skill-path>

Test a SKILL.md quality with 13 built-in assertions. Supports single skill or batch mode.

rolecraft test ./my-skill/SKILL.md       # test a single skill
rolecraft test --all                     # test all installed skills
rolecraft test --all --json              # JSON output for CI
rolecraft test ./skill --min-score 80    # fail if below 80
rolecraft test ./skill --only name,slug  # run specific assertions
rolecraft test ./skill --verbose          # detailed results
rolecraft test ./skill --no-color         # disable ANSI colors
rolecraft test ./skill --no-emoji         # ASCII fallback for emojis

rolecraft diff <skill-a> <skill-b>

Compare two SKILL.md files section-by-section. Parses frontmatter and body independently.

rolecraft diff ./a.SKILL.md ./b.SKILL.md           # full diff
rolecraft diff ./a.SKILL.md ./b.SKILL.md --brief    # summary only
rolecraft diff ./a.SKILL.md ./b.SKILL.md --json     # JSON output
rolecraft diff ./a.SKILL.md ./b.SKILL.md --no-color # no ANSI
rolecraft diff ./a.SKILL.md ./b.SKILL.md --context 3 # show 3 lines context

Output includes frontmatter changes, section-level diffs, and a summary of changed/added/removed sections.

rolecraft compose <skill-a> <skill-b> [<skill-c> ...]

Combine multiple SKILL.md files into a single composed skill.

rolecraft compose ./a.SKILL.md ./b.SKILL.md                     # stdout (merge mode)
rolecraft compose ./a.SKILL.md ./b.SKILL.md -o combined.md       # write to file
rolecraft compose ./a.SKILL.md ./b.SKILL.md --chain --name Final # chain mode
rolecraft compose ./a.SKILL.md ./b.SKILL.md --dry-run            # preview only
rolecraft compose ./a.SKILL.md ./b.SKILL.md --force              # overwrite output
rolecraft compose ./a.SKILL.md ./b.SKILL.md --json               # JSON output
rolecraft compose ./a.SKILL.md ./b.SKILL.md --no-color           # disable ANSI colors

Modes:

• merge (default): same-named sections are combined, lines deduplicated
• chain: later skills override same sections

rolecraft upgrade

Upgrades rolecraft to the latest npm version.

See also

• Node.js API — use rolecraft as a library.
• Commands — per-command pages with examples.
• Getting Started — if you have not run rolecraft yet.