Command reference

Note

This page is generated from the CLI. Do not edit it by hand; run go run ./cmd/gen-reference and commit the result.

Every gskill command and its flags, generated from the CLI grammar.

Global flags

These apply to every command.

Flag	Type	Description
--config	string	Path to a TOML config file; overrides the user config file. Must exist.
--dir	string	Run as if gskill started in this directory.
--dry-run	bool	Report actions without applying them.
--json	bool	Emit machine-readable JSON on stdout.
--no-cache	bool	Bypass the content cache.
--no-interactive	bool	Disable prompts and colored output.
--offline	bool	Operate without network access.
--quiet	bool	Suppress diagnostics on stderr.
--verbose	bool	Enable verbose diagnostics.
--yes	bool	Assume yes for confirmation prompts.

add

Add and install a new skill (auto-initializes the project if needed).

Argument	Required	Description
source	yes	Skill source: git shorthand, URL, or local path.

Flag	Type	Description
--agent	[]string	Target agent ID (repeatable). Additive: adds to, never replaces, a skill’s already-installed agents. To replace a skill’s agent set outright, use ‘gskill install –agent’.
--all	bool	Select every valid discovered skill.
--auto	bool	Prefer a symlink, fall back to a copy (default).
--commit	string	Explicit commit SHA to pin.
--copy	bool	Copy instead of linking.
--exact	bool	Pin to the exact resolved version.
--exclude	[]string	Skip skills whose in-repo path matches this glob (repeatable).
--force	bool	Overwrite an existing declaration and re-resolve.
--global	bool	Install into the user-global location.
--include	[]string	Only discover skills whose in-repo path matches this glob (repeatable).
--list	bool	List discovered skills without installing.
--max-depth	int	Maximum recursive scan depth (0 = unbounded).
--path	string	In-repo path disambiguator for a duplicated –skill.
--project	bool	Install into the project (default).
--ref	string	Branch or tag to track.
--skill	[]string	Select a discovered skill by name (repeatable; ‘*’ selects all; name@path disambiguates).
--symlink	bool	Symlink, never copy.
--version	string	Semver constraint (e.g. ^2.0.0).

cache

Manage the content cache.

cache clean

Remove all cached material.

cache list

List cached entries.

cache stats

Show the cache directory, entry count, and size.

completion

Print a shell completion script.

Argument	Required	Description
shell	yes	Shell: bash, zsh, or fish.

config

Inspect layered configuration.

config get

Print one configuration value.

Argument	Required	Description
key	yes	Configuration key.

config list

Print the config file path and the effective configuration.

dashboard (alias: tui)

Launch the interactive dashboard.

doctor

Check the environment and declared requirements.

info

Show details for one skill.

Argument	Required	Description
name	yes	Skill name.

install

Realize what skills.toml declares (resolve changes, install, record the lockfile). Never edits skills.toml.

Flag	Type	Description
--agent	[]string	Target agent(s); repeatable or comma-separated. This is the exact desired set: it replaces (not merges with) each skill’s currently recorded agents — list every agent you want kept, not just the one being added.
--copy	bool	Copy instead of symlinking (deprecated alias for –install-mode copy).
--force	bool	Accept changed upstream content: reinstall and rewrite the recorded computedHash.
--frozen-lockfile	bool	Restore exactly from the lockfile; never modify it.
--install-mode	string	How skills are placed into agent directories.
--no-init	bool	Never auto-initialize the project; fail instead.
--prune	bool	Remove managed installs whose lock entries are gone.

list

List installed skills, their status, and per-agent health.

onboard

Guided skill installation without a predefined source.

outdated

Show skills with newer versions available.

Flag	Type	Description
--exit-code	bool	Exit 8 if any update is available.

project

Manage this project’s lockfile and installed state.

project check

Report fast drift status.

Flag	Type	Description
--fail-on-drift	bool	Exit non-zero (7) if any drift is detected.

project repair

Re-materialize broken installs and clean up staging.

project sync

Reconcile disk to the lock’s declared state (–prune removes managed orphans).

Flag	Type	Description
--prune	bool	Remove managed agent targets and active entries the lock no longer declares.

project verify

Re-hash installed content against the lockfile.

remove

Uninstall skills and clean up.

Argument	Required	Description
skills	yes	Skills to remove.

Flag	Type	Description
--force	bool	Skip confirmation and remove without a terminal.

search (alias: find)

Search for skills in a source, a GitHub owner, or configured repositories.

Argument	Required	Description
query	yes	Keyword to search for (matches name and description).

Flag	Type	Description
--owner	string	Search a GitHub user/org’s repositories.
--source	string	Search within one source.

self

Manage the gskill installation itself.

self upgrade

Upgrade this gskill executable to the latest stable release, or show how its package manager upgrades it.

Flag	Type	Description
--to	string	Upgrade to this exact published release instead of the latest stable one.

update

Re-resolve declared skills to the newest revision their skills.toml constraint allows. Never edits skills.toml.

Argument	Required	Description
skills	no	Skills to update (default: all with available updates).

Flag	Type	Description
--all	bool	With –list: also report up-to-date, pinned, and local skills.
--list	bool	List available updates without applying them.
--repo	[]string	Update the skills installed from this repository (repeatable).

upgrade

Move a skill’s declared version in skills.toml, then resolve, lock, install, and verify it.

Argument	Required	Description
skill	no	Skills to upgrade. With exactly one skill, a second argument is the target version (same as –to).

Flag	Type	Description
--all	bool	Without skill names and outside a terminal: upgrade every upgradable skill.
--latest	bool	Move to the newest stable release beyond the current declaration (the default).
--to	string	Exact target version or tag; must exist as a release of the skill’s source.

version

Print the gskill version.