CLI Reference

This page lists all gaia commands, flags, and options. Follow these rules:

  • Use commands correctly: Follow each stage to run your commands.
  • Check your permissions: Anyone can use read-only commands. You must have Verifier authorization to use mutating gaia dev commands.
Local-first notes:
  • Commands show your personal skills, scan candidates, and local files.
  • Use the --canon flag to query the main registry instead.

Table of Contents

Player Workflow
Discovery
Named Skills
System & Sharing
Registry Dev

Player workflow

Use these commands to scan your local code, propose your skills to canon, and save your progress.

gaia init [--user <handle>] [--scan <path>] [--yes] [--force] [--workspace] ● open
  • Creates or updates your .gaia/config.toml configuration file.
  • Sets your GitHub handle, registry URL, and directories to scan.
  • Supports Workspace Mode for tracking skills without a public repository.
⚠️ Workspace Mode Fallback. Running gaia init outside a public Git repository automatically falls back to Workspace Mode. In Workspace Mode, local scanning is fully supported, but remote pushes are disabled. Use --workspace to force Workspace Mode. Refer to the Workspace Mode documentation for context.
Flag Description Default
--user <handle> GitHub username written to config. Used to identify your skill tree. prompted
--scan <path> Directory to scan for skill evidence. Repeatable for multiple paths. repo root
--registry-ref <url> Custom registry URL. Defaults to the public Gaia registry. public
--yes Accept all non-interactive defaults without prompting. false
--force Overwrite an existing .gaia/config.toml. false
--workspace Force Workspace Mode (disables remote pushes, enables local exploration). false
--auto-prompt-combinations Enable prompts for detected skill fusion candidates after each scan. false
examples
# Interactive setup — Gaia asks for your handle
gaia init

# Non-interactive — set handle and scan path directly
gaia init --user alice --scan src/ --yes

# Force Workspace Mode explicitly
gaia init --workspace

# Overwrite an existing config
gaia init --user alice --force
gaia scan [--quiet] [--all] [--json] [--dir DIR]... ● open
  • Scans configured paths for SKILL.md files and agent folders.
  • Saves promotion candidates to your output folder.
  • Expires scan candidate files after 24 hours.
Flag Description Default
--quiet Suppress per-file scan output; show only the final candidate summary. false
--all Scan globally installed skills in addition to the local repository. false
--json Write scan results to stdout as machine-readable JSON instead of rendering the tree. false
--dir DIR Scan an extra skill root beyond configured paths (repeatable). Accepts home-relative, absolute, or relative paths. Equivalent to adding to .gaia/config.toml skillDirs=[...]. —
examples
# Standard scan — shows detected skills and promotion candidates
gaia scan

# Quiet scan, then inspect candidates in JSON
gaia scan --quiet --json | jq '.candidates'

# Include globally installed skills, not just this repo
gaia scan --all

# Scan configured paths plus two extra directories
gaia scan --dir ~/my-skills --dir ./local-agents
gaia fuse [<skillId>] [--name <label>] ● open
  • Combines two or more skills into a higher tier.
  • Prompts you to confirm eligible skill combinations.
  • Inherits the star rank of the highest component skill.
Flag Description Default
<skillId> Target skill ID for the fusion or promotion candidate. prompted
--name <label> Optional display name for the fused skill in your tree. canonical name
examples
# Fuse an eligible combination interactively
gaia fuse

# Confirm a specific fusion target
gaia fuse autonomous-research-agent
gaia tree [--named] [--title] [--canon] [--check] ● open
  • Prints your skill tree layout to the command line.
  • Displays your unlocked skills, ranks, tiers, and slash names.
  • Uses color-coded tags to show skill star ranks.
Flag Description Default
--named Show only skills that have at least one named implementation in the registry. false
--title Show display names (lore titles) instead of slash IDs. false
--canon Show the full canonical registry tree rather than your personal unlocked view. false
--check Self-test: print every tier glyph and rank chip in resolved token colors. false
examples
# Your personal tree
gaia tree

# Show only named skills (good for contributor attribution)
gaia tree --named

# Full canonical graph with display names
gaia tree --canon --title
gaia push [--dry-run] [--no-issue] [--update] [--yes] ● open
  • Creates a draft intake batch with your detected skills.
  • Opens a review issue on the remote GitHub repository.
  • Saves the batch file under the review folder.
⚠️ Requires Repository Mode. gaia push requires a Git repository with a valid public remote origin. This command is completely disabled in Workspace Mode and will exit with an error.
Flag Description Default
--dry-run Print the skill batch to stdout without writing files or creating a GitHub issue. false
--no-issue Write the intake record to disk without creating the GitHub issue. false
--update Incremental push: skip skills already pending review for this repo. Queries open draft-skills intake issues, drops unchanged skills, keeps new and edited ones. Best-effort — falls back to a full push (which intake dedups) when GitHub is unreachable, and prints what it filtered. false
--yes, -y Skip all confirmation prompts. false
examples
# Always dry-run first
gaia push --dry-run

# Submit for real review
gaia push

# Write intake file only, no GitHub issue
gaia push --no-issue --yes

Discovery

Use these commands to search for skills, check prerequisites, and view registry stats.

gaia lookup <skillId> ● open
  • Retrieves the details card for a canonical skill.
  • Displays tiers, stars, descriptions, and prerequisites.
  • Lists named implementations, authors, and evidence.
examples
gaia lookup web-search
gaia lookup /autonomous-research-agent
gaia path <skillId> [--owned-only] [--json] ● open
  • Prints the prerequisite skill tree path for your target skill.
  • Helps plan which basic skills to obtain first.
  • Hides branches you already own when using the --owned-only flag.
Flag Description Default
--owned-only Prune branches already in your tree; show only skills still needed. false
--json Emit machine-readable JSON instead of the tree display. false
examples
# Full prerequisite tree for an ultimate skill
gaia path autonomous-research-agent

# Show only what you're still missing
gaia path autonomous-research-agent --owned-only
gaia appraise [<skillId>] ● open
  • Renders a status card for a specific skill.
  • Displays stars, possible actions (fuse, propose), evidence, and installation status.
  • Defaults to your last active skill if no argument is passed.
examples
# Appraise the last-used skill
gaia appraise

# Appraise a specific skill
gaia appraise web-search
gaia stats [--canon] ● open
  • Displays a health snapshot of the registry database.
  • Counts skills by tier, named implementations, and contributors.
  • Queries your local data by default or the canonical tree with --canon.
examples
gaia stats
gaia stats --canon
gaia graph [--format html|svg|json] [-o <path>] [--no-open] ● open
  • Generates an interactive skill dependency graph file.
  • Opens the graphical representation in your web browser.
  • Writes output to registry/render/gaia.html by default.
Flag Description Default
--format Output format: html, svg, or json. html
-o, --output <path> Write the generated graph to this path. registry/render/gaia.html
--open / --no-open Control whether the output is opened in a browser. --open
examples
# Generate and open the interactive HTML graph
gaia graph

# Export JSON without opening a browser
gaia graph --format json -o graph-snapshot.json --no-open

Named skills

Use these commands to install named skills, browse the catalog, and propose new skills.

gaia skills list | search | info | install | uninstall | update ● open
  • Manages local installations of named skills.
  • Installs skill symlinks into your agent config folder.
  • Requires a valid GitHub repository link to download.
Subcommand Description
list [--exclude-pending] List all available named skills. Pass --exclude-pending to hide draft proposals.
search <query> Full-text search across skill names, descriptions, and contributor IDs.
info <skill_id> Show detailed metadata: stars, tier, evidence, install URL, contributor.
install <skill> [--global | --local] Install a named skill into .claude/skills/ (local) or ~/.claude/skills/ (global).
uninstall <skill_id> Remove an installed named skill.
update Re-pull all installed named skills from their source URLs.
examples
# Browse all named skills
gaia skills list

# Search for research-related skills
gaia skills search research

# Inspect a specific named skill
gaia skills info karpathy/web-search

# Install globally (available to all projects)
gaia skills install karpathy/web-search --global

# Install locally into this project only
gaia skills install karpathy/web-search --local

# Update all installed skills from source
gaia skills update
gaia propose <skillId> [--target <contributor/skill>] [--yes] [--no-pr] ● open
  • Submits a proposal to claim an unclaimed canonical skill.
  • Requires Grade C (Bronze) evidence or better to propose.
  • Attaches your name as the official Origin Contributor on approval.
Flag Description Default
--target <contributor/skill> Named skill identifier in contributor/skill-name format. prompted
--yes Use defaults without interactive prompts. false
--no-pr Write the proposal locally without opening a GitHub PR. false
examples
# Propose an unclaimed canonical skill interactively
gaia propose web-search

# Propose with a specific named target
gaia propose web-search --target alice/web-search-firecrawl
gaia pull ● open
  • Refreshes your local cache from the upstream repository.
  • Updates your local copy of the main registry files.
  • Ensures scans reflect the latest canonical changes.
examples
gaia pull

System

Use these commands to check your login status, run the MCP server, and verify your files.

gaia whoami ● open
  • Prints your GitHub handle, active registry, environment mode (Repository or Workspace), and active permissions.
  • Identifies your role path (verifier, bootstrap, override, or denied).
examples
gaia whoami
# Output:
# User:      alice
# Registry:  /absolute/path/to/registry
# Mode:      Repository Mode (or Workspace Mode)
# Operator:  yes (via: bootstrap)
# Reason:    bootstrap mode active

# Check auth status in CI with the operator override
GAIA_OPERATOR_OVERRIDE=1 gaia whoami
gaia dev mcp ● open
  • Purely informational — prints install and run instructions for the standalone Gaia MCP server.
  • The server itself lives in a dedicated package, @gaia-research/mcp, not in this repo.
examples
gaia dev mcp
# Output:
#   claude mcp add gaia -- npx -y @gaia-research/[email protected]
#   Source and releases: https://github.com/gaia-research/gaia-mcp
gaia version ● open
  • Prints the current CLI software version.
  • Accepts the --version global flag as an equivalent.
examples
gaia version    # → 7.4.2
gaia --version
gaia dev validate [--intake] [--meta-sync] ● open
  • Runs structural and validation checks on the registry.
  • Verifies graph schemas, user timeline event matches, and file formats.
  • Returns exit code errors if checks fail (ideal for automation pipelines).
Flag Description Default
--intake Validate intake batches under registry-for-review/skill-batches/ instead of the canonical graph. false
--meta-sync Verify meta.json is in sync with gaia.json. false
examples
# Full validation — canonical graph + redaction + timeline integrity
gaia dev validate

# Check pending intake batches before a registry promotion
gaia dev validate --intake

# Verify meta.json is in sync
gaia dev validate --meta-sync
Used in release CI. gaia dev release calls gaia dev validate internally. Run it locally before filing a registry PR to catch schema or timeline issues early.

Sharing

Use these commands to share your skill tree with others or install shared skills.

gaia share [--user <handle>] [-o <path>] [--stdout] ● open
  • Exports a portable JSON snapshot file of your skill tree.
  • Bundles unlocked skills, installation locations, and metadata.
  • Saves the snapshot in the generated share folder by default.
Flag Description Default
--user <handle> GitHub handle whose tree to bundle. Defaults to gaiaUser from config. config value
-o, --output <path> Write the bundle to this path instead of the default location. generated-output/share/
--stdout Print the bundle JSON to stdout instead of writing a file. Useful for piping or inspection. false
examples
# Export your tree as a share bundle (writes to generated-output/share/)
gaia share

# Inspect the bundle JSON without writing a file
gaia share --stdout | jq '.install | length'

# Export to a specific path for hosting
gaia share -o ~/public/my-tree.json

# Share it — anyone with the file can preview and install
gaia install generated-output/share/alice-share-bundle.json
gaia install https://example.com/alice-share-bundle.json
gaia install <bundle.json | url | skill_id> [--install-location local|global] ● open
  • Runs as a dual-mode local package installer.
  • Processes either a bundle file link or a single named skill slug.
  • Bundle ref — a .json file path or an https:// URL: launches the guided share-bundle install flow. Shows a preview of the sharer's tree, then prompts [A]ll / [P]ick / [V]iew only / [Q]uit. Each chosen skill is resolved registry-first, then falls back to the bundle's embedded source URL.
  • Named skill — a bare slug (web-search) or a contributor/slug form: installs a single named skill into .agents/skills/ (equivalent to gaia skills install <skill>).
Flag Description Default
--install-location local|global Where to install: local places the skill in .agents/skills/ (or .claude/skills/); global places it in ~/.gaia/skills/. local
--list Open the interactive skill browser instead of installing a specific skill. false
--suite Batch-install all component skills of a suite skill. false
examples
# Install from a local share bundle (guided flow)
gaia install alice-share-bundle.json

# Install from a hosted bundle URL
gaia install https://example.com/alice-tree.json

# Install a single named skill (same as gaia skills install)
gaia install karpathy/web-search

# Install a suite of skills (batch)
gaia install garrytan/gstack --suite

# Non-TTY: defaults to view-only mode (no interactive prompt)
gaia install alice-share-bundle.json < /dev/null
Non-TTY default. When stdin is not a terminal (CI, piped), gaia install <bundle> defaults to view-only mode — it renders the sharer's tree but installs nothing. Redirect stdin from a TTY or run interactively to use the [A]ll / [P]ick prompts.

Registry dev ◇ Verifier-gated

Use these commands to edit nodes, add evidence, and manage registry data (requires Verifier authorization).

gaia dev add <name> [--type basic|fusion] [--description <text>] ... ◇ verifier
  • Adds a new skill node entry to the registry.
  • Automates modifications instead of manually editing files.
  • Rebuilds main registry files unless disabled.
Flag Description Default
--type Structural type: basic (no prerequisites) or fusion (≥1 prerequisite). basic
--description <text> Human-readable description (10+ characters required). —
--id <slug> Explicit canonical ID. Defaults to a slugified version of the name. auto
--named Add as a named skill instead of a generic node. false
--no-build Skip rebuilding docs and graph assets after adding. false
examples
# Add a new Basic skill
GAIA_OPERATOR_OVERRIDE=1 gaia dev add "Structured Output" \
  --type basic --description "Reliably emits JSON/XML/YAML matching a given schema."

# Add an Extra skill without triggering a full rebuild
GAIA_OPERATOR_OVERRIDE=1 gaia dev add "Chain-of-Thought Reasoning" \
  --type extra --no-build
gaia dev evidence <skill_id> <url> [--type <type>] [--trust <number>] [--evaluator <handle>] [--notes <text>] ◇ verifier
  • Attaches evaluation URLs to specific skill nodes.
  • Records an Evidence Type (provenance) and a Trust Magnitude number; the Evidence Grade (S/A/B/C — Platinum/Gold/Silver/Bronze) is auto-derived from the number, never set directly.
  • Influences the speed of skill star upgrades.
⚠️ --class is deprecated. The legacy --class A|B|C flag still works for backward compatibility, but new evidence should always use --type + --trust. Class letters and Grade letters are not equivalent — see Evidence & Trust — common pitfalls.
Flag Description Default
--type <type> Evidence Type — provenance of the demonstration. Validated against meta.json evidence.types (e.g. repo-own, github-stars-own, arxiv, peer-review, benchmark-result, self-attestation, social-signal). —
--trust <number> Trust Magnitude value. Evidence Grade is auto-derived: S ≥ 250, A ≥ 100, B ≥ 50, C ≥ 20; below 20 is ungraded. —
--class A|B|C [DEPRECATED] Legacy evidence quality class. Prefer --trust. —
--stars / --commits / --contributors <N> Type-specific metrics (e.g. star count for github-stars-own, commit/contributor counts for repo-own) used by the Trust Magnitude formula for that type. —
--evaluator <handle> GitHub username of the person submitting this evidence. whoami handle
--date <YYYY-MM-DD> Date of evaluation (ISO 8601). today
--notes <text> Context note attached to this evidence entry. —
--no-build Skip rebuilding docs and graph assets after adding evidence. false
examples
# Add repo-own evidence (Trust 20 → Grade C / Bronze)
GAIA_OPERATOR_OVERRIDE=1 gaia dev evidence \
  web-search https://github.com/anthropics/cookbook --type repo-own --trust 20

# Add arXiv evidence with an evaluator note (Trust 100 → Grade A / Gold)
GAIA_OPERATOR_OVERRIDE=1 gaia dev evidence \
  autonomous-research-agent https://arxiv.org/abs/2401.00000 \
  --type arxiv --trust 100 --evaluator alice --notes "Peer-reviewed benchmark, 2024"
gaia dev merge <target-id> <source-id…> ◇ verifier
  • Merges multiple source nodes into a single target node.
  • Consolidates all evidence and named implementations.
  • Deletes source nodes and preserves links.
examples
GAIA_OPERATOR_OVERRIDE=1 gaia dev merge web-search web-search-v1 web-search-v2
gaia dev split <source-id> <target-id…> ◇ verifier
  • Splits one skill node into two or more new nodes.
  • Requires manual evidence re-assignment after the split.
examples
GAIA_OPERATOR_OVERRIDE=1 gaia dev split web-automation web-scraping browser-control
gaia dev rename <old-id> <new-id> ◇ verifier
  • Renames a generic skill ID or a Named Skill (contributor/slug) and rewrites every reference surface: prerequisites/derivatives in other nodes, genericSkillRef and suiteComponents/suiteRef in named skill files, suite manifests, and user skill trees.
  • Rewrites prose references (install commands, cross-links) but leaves changelog/history sections untouched — they record what the skill was called at the time.
  • Logs a rename timeline event automatically. No separate gaia dev timeline call needed.
  • Fails if new-id already exists in the registry.
examples
# Rename a generic node
GAIA_OPERATOR_OVERRIDE=1 gaia dev rename web-search web-search-and-retrieval

# Rename a Named Skill
GAIA_OPERATOR_OVERRIDE=1 gaia dev rename marco/old-slug marco/new-slug
gaia dev timeline <skillId> --user <handle> --action <action> [--notes <text>] [--timestamp <ISO8601>] ◇ verifier
  • Appends a timeline action to a skill's log.
  • Requires the --user flag to write to user skill tree files.
  • Supports historical timestamps for backfilling events.
Known gap. gaia dev timeline without --user writes to the registry node, not the user tree. Always pass --user <handle> when appending to a skill tree.
Flag Description Default
--user <handle> Target the user's skill-tree.json (required for tree edits). —
--action <action> Event type, e.g. rank_up, demote, fuse, backfill. —
--notes <text> Human-readable description appended to the event. —
--timestamp <ISO8601> Historical timestamp. Backfilled events are sorted chronologically. now (UTC)
examples
# Append a current-time event to alice's tree
GAIA_OPERATOR_OVERRIDE=1 gaia dev timeline web-search \
  --user alice --action rank_up --notes "Promoted to 3★ Evolved"

# Backfill a historical event
GAIA_OPERATOR_OVERRIDE=1 gaia dev timeline web-search \
  --user alice --action rank_up \
  --timestamp 2026-01-15T00:00:00Z --notes "Backfilled (direct edit — CLI gap)"
gaia dev list [--generic] [--named] [--description] [--json] ... ● open
  • Lists all skills registered in the database.
  • Projects custom metadata fields for scripting and automation.
  • Combines flags to retrieve different skill tiers simultaneously.
examples
# List all generic skills with descriptions
gaia dev list --generic --description

# List named skills with contributor info as JSON
gaia dev list --named --contributor --json
gaia dev audit ● open
  • Audits registry files for errors, broken links, or format issues.
  • Outputs a prioritized task list of schema failures.
  • Runs read-only without modifying registry data.
examples
gaia dev audit
gaia dev diff  # show substantive changes vs main
gaia dev sync-upstream <skill-id> --tag <tag> --source-url <url> [--bootstrap] [--released-at <timestamp>] [--mode {components,version-only}] [--dry-run] [--user <user>] ◇ verifier
  • Writes or updates the upstream: frontmatter block in a named skill file.
  • Appends an upstream_synced event atomically to the skill's timeline log.
  • Validates release tag formats and checks that the release repository matches the skill's GitHub link.
❖ Upstream watch. Enforces strict pre-flight checks: the skill must exist under registry/named/, must be rated 2★ or higher, and the --tag and --source-url formats must be valid.
Flag Description Default
<skill-id> The unique ID of the named skill (e.g. mattpocock/skills). required
--tag <tag> The release tag to sync (must match a version pattern like v1.2.3). required
--source-url <url> GitHub releases URL: https://github.com/<owner>/<repo>/releases/tag/<tag>. required
--bootstrap First-time write. Refuses if the upstream: block already exists. false
--released-at <timestamp> ISO 8601 release timestamp. If omitted, uses the current UTC time. now
--mode {components,version-only} Upstream tracking mode (tracks components or version only). components
--dry-run Prints intended changes without writing. false
--user <user> Contributor handle attributed to the timeline event. Defaults to whoami actor. whoami
examples
# Bootstrap an upstream tracking block for a 2★+ named skill
GAIA_OPERATOR_OVERRIDE=1 gaia dev sync-upstream mattpocock/skills --tag v1.0.0 --source-url https://github.com/mattpocock/skills/releases/tag/v1.0.0 --bootstrap

# Update a skill to a new upstream version
GAIA_OPERATOR_OVERRIDE=1 gaia dev sync-upstream mattpocock/skills --tag v1.1.0 --source-url https://github.com/mattpocock/skills/releases/tag/v1.1.0
gaia dev freeze <skill-id> --reason <text> [--dry-run] [--user <user>] ◇ verifier
  • Sets installable: false in a named skill's frontmatter.
  • Appends an upstream_deprecated event atomically to the skill's timeline log.
  • Provides a safe, structured way to deprecate unmaintained or broken named skills.
⚠️ Deprecation Check. Enforces strict pre-flight checks: the skill must exist under registry/named/, the --reason must be non-empty and ≤500 characters, and refuses if the skill is already frozen. Warns (does not refuse) if the skill is 3★+ since the Star Bar rules may fail.
Flag Description Default
<skill-id> The named skill ID to freeze (e.g. mattpocock/old-skill). required
--reason <text> Human-readable explanation of why the skill is being frozen (≤500 chars). required
--dry-run Prints intended changes without writing. false
--user <user> Contributor handle attributed to the timeline event. Defaults to whoami actor. whoami
examples
# Freeze an unmaintained named skill with a reason
GAIA_OPERATOR_OVERRIDE=1 gaia dev freeze mattpocock/old-skill --reason "unmaintained, repository archived by owner"

Global flags

Use these flags with any gaia command to change how it runs.

Flag Description
--canon Show canonical registry data instead of the local-first (personal) view.
--global, -g Use the global GAIA_HOME registry, ignoring any local .gaia/ config.
--registry <path> Point to a specific local registry checkout instead of auto-resolving.
--tui Launch the interactive TUI dashboard instead of the command-line output.
--version, -v Print the installed CLI version and exit.
← Getting Started Skill Hierarchy →