Skip to content

CLI Reference

Jump to bottom
github-actions[bot] edited this page Jun 25, 2026 · 5 revisions

CLI Reference

The command-line interface is the primary tool for interacting with the Gaia registry.

Global Options

The following options apply to all gaia commands:

  • --registry PATH: Path to a local Gaia registry checkout. Defaults to auto-resolved local or global registry.
  • --global, -g: Use global GAIA_HOME registry, ignoring any local .gaia/ config.
  • --version, -v: Print the Gaia CLI version and exit.
  • --tui: Launch the TUI (Terminal User Interface).
  • --canon: Show canonical registry data instead of local-first view.
  • -h, --help: Show the help message and exit.

gaia init

Initialize a local .gaia/config.json configuration file, scan repository.

gaia init [--user USER] [--registry-ref REGISTRY_REF] [--scan SCAN] [--yes] [--force] [--auto-prompt-combinations]
  • --user USER: Gaia username to write into config.
  • --scan SCAN: Path to scan; repeat for multiple paths.
  • --yes, -y: Use non-interactive defaults.
  • --force: Overwrite existing configuration.
  • --auto-prompt-combinations: Enable automatic prompts for detected skill combinations.

gaia scan

Scan local files for skill indicators/signatures, reporting what skills are present in code.

gaia scan [--quiet] [--json] [--all]
  • --quiet: Suppress scan output; only show notifications.
  • --json: Output scan results as JSON.
  • --all: Scan globally installed skills in addition to the local repository.

gaia pull

Re-fetch the remote skill registry and download the latest assets to local cache.

gaia pull

gaia update

Update the local registry metadata (alias for pull/sync).

gaia update

gaia tree

Prints/renders the skill tree or DAG, either local or global, optionally showing named skills.

gaia tree [--named] [--title] [--canon] [--check] [--custom] [--all]
  • --named: Show only skills that have a named implementation.
  • --title: Show display name instead of slash command / contributor ID.
  • --canon: Show canonical registry data instead of custom skills only.
  • --check: Self-test: print all tier glyphs and rank chips in resolved token colors.
  • --custom: Show only custom skills (default).
  • --all, -a: Show all prerequisites including unowned (/??? entries).

gaia push

Pushes the scanned local skills to the review intake (registry-for-review), creates a PR.

gaia push [--dry-run] [--no-issue] [--yes] [--allow-unsafe] [--reason REASON]
  • --dry-run: Print the skill batch without writing it.
  • --no-issue: Write intake record without creating a GitHub issue.
  • --yes, -y: Skip confirmation prompts.
  • --allow-unsafe: Override the security scanner block on high-severity findings (requires --reason).
  • --reason REASON: Document an --allow-unsafe override for the audit trail.

gaia propose

Claims a skill (especially Ultimate skill) with an implementation repo or PR.

gaia propose <skillId> [--target TARGET] [--ultimate] [--yes] [--no-pr]
  • skillId: Canonical skill ID (accepts /skill-id form).
  • --target TARGET: Named skill target in contributor/skill-name format.
  • --ultimate: Require that the selected skill is ultimate.
  • --yes, -y: Use defaults without interactive prompts.
  • --no-pr: Write intake proposal without opening a PR.

gaia appraise

Shows details about a skill, its prerequisites, and trust metrics (like Trust Magnitude, evidence list, etc.).

gaia appraise [skillId]
  • skillId: Skill ID to appraise (default: most recent).

gaia promote

Promotes a skill (ranks up / levels up) by evaluating its evidence and updating status/level.

gaia promote [skillId] [--all] [--unique] [--name NAME]
  • skillId: Skill ID to promote.
  • --all: Promote every candidate from the last scan.
  • --unique: Promote a basic skill to unique type (4★+ graph-isolated with named impl).
  • --name NAME: Optional display name for the promoted skill.

gaia fuse

Fuses prerequisites into an Extra or Ultimate skill (registers fusion).

gaia fuse [skillId] [--name NAME] [--skills SKILLS] [--delete]
  • skillId: Skill ID to fuse or promote.
  • --name NAME: Optional display name for the skill.
  • --skills SKILLS: Comma-separated list of skills to combine for a custom fusion.
  • --delete: Delete an existing custom fusion.

gaia stats

Prints registry statistics (number of basic, extra, unique, ultimate skills, etc.).

gaia stats [--canon]
  • --canon: Show canonical registry data instead of local-first view.

gaia graph

Exports the skill graph as HTML, SVG, or JSON, or opens it.

gaia graph [--format {html,svg,json}] [-o OUTPUT] [--open] [--no-open] [--custom] [--canon] [--all]
  • --format {html,svg,json}: Graph encoding format.
  • -o, --output OUTPUT: Output path.
  • --open: Open the generated graph.
  • --no-open: Do not open the generated graph.
  • --custom: Only include custom skills in the graph.
  • --canon: Show canonical registry graph instead of custom skills only.
  • --all, -a: Include unowned prerequisite nodes in the graph.

gaia skills

Browse, search, install, or update named skills.

gaia skills <list|search|info|install|update|uninstall>
  • gaia skills list [--exclude-pending]
  • gaia skills search <query> [--exclude-pending]
  • gaia skills info <skill_id> [--exclude-pending]
  • gaia skills install <skill> [--global | --local]
  • gaia skills update
  • gaia skills uninstall <skill_id>

gaia mcp

Start the Gaia MCP (Model Context Protocol) server, which exposes the skill registry to AI tools and IDE integrations via stdio.

gaia mcp

(Note: Requires building the server first: run npm run build inside packages/mcp/)

gaia version

Print the version of the Gaia CLI and registry.

gaia version

gaia release

Bumps the registry version across all manifests.

gaia release [--sync] [--no-push] {patch,minor,major}

Warning

gaia release is DEPRECATED and will be removed in v7.0.0. Use gaia dev release instead.

gaia docs

Build generated documentation regions.

gaia docs build [--check]

Warning

gaia docs build is DEPRECATED and will be removed in v7.0.0. Use gaia dev docs instead.

Environment and Config

  • GAIA_HOME / GAIA_REGISTRY: Directory containing the active Gaia registry checkout.
  • GAIA_USER: GitHub username used by the MCP server and CLI.
  • GITHUB_TOKEN: Optional GitHub Personal Access Token to enable PR creations and API lookups.
  • ~/.gaia/config.toml: Local Gaia configuration (user, registry reference, etc.).

Quick Reference

Quick Reference

The complete gaia --help output:

usage: gaia [-h] [--registry REGISTRY] [--global] [--version]
            {help,init,scan,fetch,pull,update,install,uninstall,share,tree,push,propose,version,whoami,login,logout,reset,graph,stats,appraise,promote,fuse,lookup,path,dev,skills}
            ...

Gaia Registry CLI

options:
  -h, --help           show this help message and exit
  --registry REGISTRY  Path to a local Gaia registry checkout. Defaults to auto-resolved local or
                       global registry.
  --global, -g         Use global GAIA_HOME registry, ignoring any local .gaia/ config.
  --version, -v        Print the Gaia CLI version and exit.
  --tui                Launch the TUI (Terminal User Interface).
  --canon              Show canonical registry data instead of local-first view.

Getting started:
  gaia init [--user <name>] [--scan <path>] [--yes] [-y]
  gaia scan [--quiet]
  gaia push [--dry-run] [--no-issue]
  gaia                        Open command selector
  gaia skills                 Launch skills explorer (TUI)

Daily commands:
  gaia tree [--named] [--title]
  gaia promote [<skillId>] [--all] [--name <name>]
  gaia appraise [<skillId>]
  gaia stats
  gaia pull
  gaia fuse <skillId> [--name <name>]
  gaia path <skillId> [--owned-only] [--json]
  gaia lookup <skillId>
  gaia graph [--format html|svg|json] [-o <path>] [--no-open]
  gaia propose [<skillId>] [--ultimate] [--target <name>] [--no-pr]

Skills:
  gaia skills <list|search|info|install|uninstall>
  gaia skills list [--exclude-pending]
  gaia skills search <query> [--exclude-pending]
  gaia skills info <skill_id> [--exclude-pending]
  gaia skills install <skill> [--global | --local]
  gaia skills uninstall <skill_id>

Share:
  gaia share [--user <name>] [-o <path>] [--stdout]
  gaia install <bundle.json|url>   Preview & install a shared tree (guided)

Utilities:
  gaia whoami
  gaia login                    Sign in with GitHub (device flow)
  gaia logout                   Sign out of GitHub (clears the local token)
  gaia version
  gaia update
  gaia dev mcp
  gaia dev release <patch|minor|major>
  gaia dev docs [--check]

Maintainer commands:  gaia dev --help

Clone this wiki locally