Skip to content

CLI Reference

Jump to bottom
mbtiongson1 edited this page May 18, 2026 · 5 revisions

CLI Reference

Complete reference for every gaia command.

Install:

pip install gaia-cli
# or
npm install -g @gaia-registry/cli

For registry development, install editable:

git clone https://github.com/mbtiongson1/gaia-skill-tree.git
cd gaia-skill-tree
pip install -e ".[embeddings]"

Global Options

Option Description
--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.
--canon Show canonical registry data instead of local-first view.

gaia init

Creates or updates .gaia/config.json in the current directory.

gaia init
gaia init --user your-username
gaia init --user your-username --scan src --scan scripts --yes
Flag Description
--user NAME GitHub username to write into config
--scan PATH Path to scan; repeat for multiple paths
--yes Use non-interactive defaults

Edit gaiaUser (your GitHub username) and scanPaths before running gaia scan.

gaia scan

Scans configured paths and reports detected canonical skills and possible fusions.

gaia scan
gaia scan --quiet
gaia scan --auto-promote
Flag Description
--quiet Suppress scan output; only show notifications
--auto-promote Promote every scan-recommended candidate after scanning

Output: count and list of detected canonical skill IDs, combination candidates, and fusion diagrams. Writes generated-output/promotion-candidates.json and renders your tree to generated-output/tree.{html,md}.

gaia pull

Refreshes registry data from origin.

gaia pull

gaia update

Pulls the latest registry and reinstalls the CLI.

gaia update

Equivalent to gaia pull + pip install --upgrade gaia-cli (with pipx fallback). Run this to stay current without reinstalling manually.

gaia tree

Shows your Gaia skill tree with rank-colored display.

gaia tree
gaia tree --named
gaia tree --title
Flag Description
--named Show only skills that have a named implementation
--title Show display name instead of slash command / contributor ID

gaia push

Builds a skill batch from the current scan and writes it to the registry for review.

gaia push --dry-run    # preview without writing
gaia push              # write batch + open a draft PR
gaia push --no-pr      # write batch without opening a PR
Flag Description
--dry-run Print the batch JSON to stdout without writing files
--no-pr Write the intake record without attempting to open a GitHub PR

The batch is written to registry-for-review/skill-batches/<batchId>.json. Each proposed skill gets "lifecycle": "pending".

gaia propose

Proposes a single canonical skill as a named PR. Interactive by default.

gaia propose web-search
gaia propose /autonomous-debug --target yourname/my-debugger
gaia propose recursive-self-improvement --ultimate
Argument/Flag Description
skillId Canonical skill ID (accepts /skill-id form)
--target NAME Named skill target in contributor/skill-name format
--ultimate Require that the selected skill is ultimate
--yes Use defaults without interactive prompts
--no-pr Write intake proposal without opening a PR

gaia appraise

Inspects a skill plaque with status, rank, demerits, evidence, and available actions.

gaia appraise
gaia appraise web-search
gaia appraise autonomous-debug

If no skillId is given, appraises the most recently touched skill. Shows effective rank (accounting for demerits), evidence entries, and promotion eligibility.

gaia promote

Promotes a skill eligible for rank-up based on the last scan.

gaia promote
gaia promote web-search
gaia promote --all
gaia promote web-search --name "Web Search"
Argument/Flag Description
skillId Skill ID to promote (default: most recent candidate)
--all Promote every candidate from the last scan
--name NAME Optional display name for the promoted skill

gaia fuse

Confirms a skill combination or promotion candidate.

gaia fuse
gaia fuse rag-pipeline
gaia fuse rag-pipeline --name "My RAG Pipeline"
Argument/Flag Description
skillId Skill ID to fuse or promote
--name NAME Optional display name

skillId must be in your pending combination candidates, populated by gaia scan.

gaia stats

Shows registry health at a glance — skill counts by type and rank, evidence coverage, and pending review items.

gaia stats

gaia graph

Generates and opens the Gaia skill graph.

gaia graph
gaia graph --format svg
gaia graph --format json -o my-graph.json --no-open
Flag Description
--format html|svg|json Graph artifact format (default: html)
-o PATH Output path (default: registry/render/gaia.html)
--no-open Generate without opening the file

gaia skills

Browse and manage named skills.

gaia skills list
gaia skills list --exclude-pending
gaia skills search "autonomous research"
gaia skills info karpathy/autoresearch
gaia skills install karpathy/autoresearch
gaia skills install karpathy/autoresearch --global
gaia skills install karpathy/autoresearch --local
gaia skills uninstall karpathy/autoresearch
Subcommand Description
list List all available named skills
search <query> Search named skills by name or description
info <skill_id> Show full details for a named skill
install <skill> Install a named skill (accepts ID, catalogRef, or bare slug)
uninstall <skill_id> Uninstall a named skill

--global installs to ~/.gaia/skills/; --local installs to .gaia/skills/ in the current project.

gaia mcp

Runs the bundled Gaia MCP server.

gaia mcp

For agent-specific config and environment variables, see MCP Server.

gaia version

Prints the Gaia CLI version.

gaia version

gaia release

Bumps release version files (maintainers only).

gaia release patch
gaia release minor
gaia release major

gaia docs

Documentation maintenance commands.

gaia docs build          # regenerate generated documentation regions
gaia docs build --check  # fail if docs are stale without writing

Environment and Config

File / Variable Purpose
.gaia/config.json Per-project config (user, registry ref, scan paths)
registry-for-review/skill-batches/ Intake batch records written by gaia push
generated-output/ Local scan and render output (gitignored)
~/.gaia/skills/ Global named skill cache
GAIA_USER GitHub username used by the MCP server
GITHUB_TOKEN Optional token for PR tools in the MCP server

Clone this wiki locally