description	Complete reference for every rolecraft command, flag and option, including install, bundle, CI, MCP and profile subcommands.
outline	false

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.

Navigation Menu

Repository navigation

reference.md

reference.md

CLI Reference

Commands

Common flags

Exit codes

Environment

Agent-specific flags

Subcommand detail

`rolecraft init [name]`

`rolecraft install <source>`

`rolecraft bundle <sources...>`

`rolecraft use <source>`

`rolecraft list`

`rolecraft remove <slug>`

`rolecraft update <slug>`

`rolecraft setup [<source>]`

`rolecraft search <query>`

`rolecraft check`

`rolecraft ci`

`rolecraft verify`

`rolecraft doctor`

`rolecraft watch [<slug>]`

`rolecraft convert <source>`

`rolecraft profile`

`rolecraft mcp`

`rolecraft agents-xml [--write]`

`rolecraft completions bash|zsh|fish`

`rolecraft test <skill-path>`

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

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

`rolecraft upgrade`

See also

FilesExpand file tree

reference.md

Latest commit

History

reference.md

File metadata and controls

CLI Reference

Commands

Common flags

Exit codes

Environment

Agent-specific flags

Subcommand detail

rolecraft init [name]

rolecraft install <source>

rolecraft bundle <sources...>

rolecraft use <source>

rolecraft list

rolecraft remove <slug>

rolecraft update <slug>

rolecraft setup [<source>]

rolecraft search <query>

rolecraft check

rolecraft ci

rolecraft verify

rolecraft doctor

rolecraft watch [<slug>]

rolecraft convert <source>

rolecraft profile

rolecraft mcp

rolecraft agents-xml [--write]

rolecraft completions bash|zsh|fish

rolecraft test <skill-path>

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

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

rolecraft upgrade

See also

`rolecraft init [name]`

`rolecraft install <source>`

`rolecraft bundle <sources...>`

`rolecraft use <source>`

`rolecraft list`

`rolecraft remove <slug>`

`rolecraft update <slug>`

`rolecraft setup [<source>]`

`rolecraft search <query>`

`rolecraft check`

`rolecraft ci`

`rolecraft verify`

`rolecraft doctor`

`rolecraft watch [<slug>]`

`rolecraft convert <source>`

`rolecraft profile`

`rolecraft mcp`

`rolecraft agents-xml [--write]`

`rolecraft completions bash|zsh|fish`

`rolecraft test <skill-path>`

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

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

`rolecraft upgrade`