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, promote your skills, 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] [--auto-promote] [--json] ● 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
--auto-promote Automatically promote every scan candidate without prompting. false
--json Write scan results to stdout as machine-readable JSON instead of rendering the tree. false
examples
# Standard scan — shows detected skills and promotion candidates
gaia scan

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

# Promote everything the scanner detects, no prompts
gaia scan --auto-promote
gaia promote [<skillId>] [--all] [--unique] [--name <label>] ● open
  • Promotes one skill or all candidates from your last scan.
  • Requires candidate skills to be listed in a non-stale file.
  • Appends a timeline event to your skill tree file.
Flag Description Default
<skillId> Slash-prefixed or bare canonical skill ID, e.g. /web-search or web-search. —
--all Promote every candidate from the most recent scan in one pass. false
--unique Promote a Basic skill to the Unique tier (requires 4★ and graph-isolation with a named implementation). false
--name <label> Optional display name for the skill entry in your tree. canonical name
examples
# Promote a single skill after scanning
gaia scan
gaia promote /web-search

# Promote every candidate from the last scan
gaia promote --all

# Promote a Basic skill to Unique tier
gaia promote code-review --unique
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] [--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
--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 (promote, 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>] [--ultimate] [--yes] [--no-pr] ● open
  • Submits a proposal to claim an unclaimed canonical skill.
  • Requires Class C 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
--ultimate Assert the skill is an Ultimate. Fails if it is not. false
--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
  • Launches the Gaia MCP server over standard input/output.
  • Exposes the skill registry metadata directly to your AI agent.
  • Requires compiling the MCP code before running.
examples
# Build the MCP server once
cd packages/mcp && npm run build

# Start the server (typically invoked by your IDE/agent config)
gaia dev mcp
gaia version ● open
  • Prints the current CLI software version.
  • Accepts the --version global flag as an equivalent.
examples
gaia version    # → 4.7.7
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
--ultimate, --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|extra|unique|ultimate] [--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 Tier: basic, extra, unique, or ultimate. 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> [--class A|B|C] [--evaluator <handle>] [--notes <text>] ◇ verifier
  • Attaches evaluation URLs to specific skill nodes.
  • Categorizes evidence into levels A (high), B (medium), or C (low).
  • Influences the speed of skill star upgrades.
Flag Description Default
--class A|B|C Evidence quality class. C
--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. —
examples
# Add Class B evidence (reproducible repo link)
GAIA_OPERATOR_OVERRIDE=1 gaia dev evidence \
  web-search https://github.com/anthropics/cookbook --class B

# Add Class A evidence with an evaluator note
GAIA_OPERATOR_OVERRIDE=1 gaia dev evidence \
  autonomous-research-agent https://arxiv.org/abs/2401.00000 \
  --class A --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 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

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 →