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`

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

`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`