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>] [--skills <ids>] [--delete] ● open
  • Fuses two or more skills into one, declared locally as type: fusion.
  • Prompts you to confirm a scan-detected combination, or declares a new custom fusion path.
  • Levelless — no rank is inherited or assigned locally. Canon curation assigns rank after gaia push.
Flag Description Default
<skillId> Target skill ID; with --skills, supply it positionally or with --name. Also selects the custom fusion to delete. prompted
--name <label> In the --skills path, supplies the target skill ID when no positional target is given. —
--skills <ids> Comma-separated source skill IDs for a custom fusion. Saves it locally in .gaia/custom_state.json; it does not immediately edit the skill tree. —
--delete Removes only the custom fusion entry; does not change the registry or skill tree. Prompts for a selection when no target is supplied in an interactive shell. false
examples
# Fuse an eligible combination interactively
gaia fuse

# Confirm a specific fusion target
gaia fuse autonomous-research-agent

# Declare a local custom fusion from source skills
gaia fuse get-shit-done --skills planning,execution

# Delete a custom fusion
gaia fuse get-shit-done --delete
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 instructions for the Skill Heaven plugin and bundled summon MCP server.
  • Standalone @gaia-research/mcp was decommissioned on 2026-08-19.
examples
gaia dev mcp
# Output:
#   Gaia summon MCP — bundled in the Skill Heaven plugin
#
#   Standalone @gaia-research/mcp was decommissioned on 2026-08-19.
#   Summon now ships inside the Skill Heaven plugin, which bundles its
#   own MCP server — there is nothing to configure separately.
#
#     claude plugin install skill-heaven@gaia-skill-heaven
#
#   Source and releases: https://github.com/gaia-research/gaia-skill-heaven
gaia version ● open
  • Prints the current CLI software version.
  • Accepts the --version global flag as an equivalent.
examples
gaia version    # → 7.7.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.
gaia steward {scan, run, dispatch, lane, verify, founder} [options] ● open
  • Autonomous repository maintenance steward and debt reconciliation engine.
  • Runs local read-only sensors, manages bounded maintenance lanes, and handles patch verification.
  • Enforces strict policy boundaries: never executes arbitrary commands or spends unbounded agent turns.
Subcommand / Flag Description Default
scan [--json] Run local sensors to detect and report repository maintenance debt. Writes receipts strictly under .gaia/steward/. —
run [--json] Execute at most one policy-authorized Class A debt repair with automated independent proof. —
dispatch <debt_id> [--prompt] [--json] Render a report-only Class B task packet or agent prompt for a specific maintenance debt. —
lane status [--json] Report the state of the bounded rolling maintenance lane. —
lane next [--prompt] [--json] Hand out the next eligible bounded task from the lane (agent pickup point). —
lane record <debt_id> --verdict {accept,reject,escalate} [--note <text>] Record an independent verifier's judgment on a completed maintenance dispatch. —
verify <debt_id> --diff <diff> --proof <json> [--prompt] Independently verify a candidate patch against the envelope recorded in its dispatch receipt. —
founder [--json] Render the report-only Class C founder decision queue for unresolved discovery candidates. —
examples
# Scan current repository maintenance debt
gaia steward scan

# Pick up the next bounded maintenance task as an agent prompt
gaia steward lane next --prompt

# Run policy-authorized single Class A repair
gaia steward run

# Record an independent verification decision
gaia steward lane record debt-001 --verdict accept --note "Verified clean by CI"

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
--build Rebuild docs and graph assets after adding (opt-in; slower). false
--no-build Skip rebuilding docs and graph assets after adding. No-op alias — this is already the default. true
Docs rebuild is opt-in: a mutating command skips gaia dev docs regeneration by default. Pass --build when you need the rebuild in the same step (e.g. before manually inspecting docs/graph/).
examples
# Add a new Basic skill (no docs rebuild, the default)
GAIA_OPERATOR_OVERRIDE=1 gaia dev add "Structured Output" \
  --type basic --description "Reliably emits JSON/XML/YAML matching a given schema."

# Add a Fusion skill with its prerequisites, and rebuild docs/graph assets in the same step
GAIA_OPERATOR_OVERRIDE=1 gaia dev add "Chain-of-Thought Reasoning" \
  --type fusion --description "Reasons through multi-step problems using structured chains of thought." \
  --extra-fields '{"prerequisites": ["structured-output"]}' --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. —
--build Rebuild docs and graph assets after adding evidence (opt-in; slower). false
--no-build Skip rebuilding docs and graph assets after adding evidence. No-op alias — this is already the default. true
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 rm-evidence <skill-id> (--index <N> | --source <URL>) [--yes] [--build] ◇ verifier
  • Removes an evidence entry from a skill node by index number or matching source URL.
  • Prompts for confirmation unless --yes is provided.
  • Skips documentation rebuild by default. Pass --build to regenerate artifacts.
Flag Description Default
<skill-id> Skill ID to remove evidence from. required
--index <N> 0-based index of the evidence entry to remove. —
--source <URL> Source URL to match and remove. —
--yes, -y Skip interactive confirmation prompt. false
--build Rebuild site documentation after removing evidence. false
examples
# Remove evidence by source URL
GAIA_OPERATOR_OVERRIDE=1 gaia dev rm-evidence web-scrape --source https://example.com/stale-paper.pdf --yes

# Remove evidence by index
GAIA_OPERATOR_OVERRIDE=1 gaia dev rm-evidence web-scrape --index 0
gaia dev verify <skill-id> --index <N> [--dispute] [--notes <text>] [--source <url>] [--build] ◇ verifier
  • Verifies or disputes an existing evidence row attached to a skill node.
  • Records the verifier attestation with optional dispute rationale and discussion URL.
  • Skips documentation rebuild by default. Pass --build to regenerate artifacts.
Flag Description Default
<skill-id> Skill ID containing the evidence entry. required
--index <N> 0-based index of the evidence row to verify. required
--dispute Flag the evidence as disputed rather than verified. false
--notes <text> Notes explaining the verification or dispute finding. —
--source <url> URL to the audit PR or discussion thread. —
--build Rebuild site documentation after recording verification. false
examples
# Verify an evidence row
GAIA_OPERATOR_OVERRIDE=1 gaia dev verify web-scrape --index 0 --notes "Confirmed working upstream repository"

# Dispute an invalid benchmark row
GAIA_OPERATOR_OVERRIDE=1 gaia dev verify web-scrape --index 1 --dispute --notes "Dead URL 404"
gaia dev calibrate <contributor/skill-id> <level> ◇ verifier
  • Sets a Named Skill's star level directly (1★–6★).
  • Stars live only on named skills — a generic reference has no level to set.
  • Logs a rank_up or demote timeline event automatically.
⚠️ 3★+ requires a verified repo link. Calibrating to 3★ or higher checks for a links.github value containing /blob/ (the Star Bar rule, META.md §2.4) and refuses the write otherwise — unless the skill has suiteComponents, which derive trust from their components instead of a personal repo link.
Flag Description Default
--build Rebuild docs and graph assets after calibrating (opt-in; slower). false
--no-build Skip rebuilding docs and graph assets after calibrating. No-op alias — this is already the default. true
examples
# Calibrate a named skill to 3★ (requires a blob/ repo link already on file)
GAIA_OPERATOR_OVERRIDE=1 gaia dev calibrate mattpocock/skills 3★

# Demote back to 2★
GAIA_OPERATOR_OVERRIDE=1 gaia dev calibrate mattpocock/skills 2★
gaia dev calibrate-evidence-grades [--skill <id>] [--scope all|generic|named] [--dry-run] [--yes] ◇ verifier
  • Backfills each evidence row's per-row Evidence Grade from its artifact score, using the thresholds in meta.json.
  • Walks every generic node and named skill file, or just one skill with --skill.
  • Skips auto-derived rows (_autoDerived: true) — those are computed, not stored.
Flag Description Default
--dry-run Show what would change without writing. false
--skill <id> Only process this skill (generic ref or contributor/name). all skills
--scope Limit to generic nodes, named files, or all. all
--yes / -y Skip the confirmation prompt. false
examples
# Preview grade backfill for one named skill first
gaia dev calibrate-evidence-grades --skill mattpocock/skills --dry-run

# Apply it across the whole registry without a confirmation prompt
GAIA_OPERATOR_OVERRIDE=1 gaia dev calibrate-evidence-grades --yes
gaia dev calibrate-trust-magnitude (--skill <contributor/id>... | --all) [--dry-run] [--yes] ◇ verifier
  • Refreshes the cached trustMagnitude, overallTrustGrade, and trustMagnitudeInputHash frontmatter fields from the live Trust Magnitude formula.
  • These three fields are a disposable cache — the generated site already recomputes the live value on every build, but a named skill's own frontmatter stays frozen until this verb re-stamps it.
  • Closes the CLI gap earlier migration timeline entries flagged: before this verb existed, only an archived one-off script could write these fields.
Flag Description Default
--skill <contributor/id> Named skill to refresh. Repeatable. Mutually exclusive with --all. —
--all Refresh every named skill in the registry. false
--dry-run Show the old → new Trust Magnitude / grade without writing. false
--yes / -y Skip the confirmation prompt. false
examples
# Preview the refresh for two named skills
gaia dev calibrate-trust-magnitude --skill mattpocock/skills --skill mattpocock/engineering --dry-run

# Refresh every named skill's cached Trust Magnitude fields
GAIA_OPERATOR_OVERRIDE=1 gaia dev calibrate-trust-magnitude --all --yes
gaia dev fuse <generic-id> [--name <name>] [--description <desc>] [--prereqs <ids>] [--named-capstone <contributor/slug>] [--suite-components <ids>] [--build] ◇ verifier
  • Creates or updates a starless generic fusion node (registry/nodes/fusion/<generic-id>.json) and optional suite manifest (registry/suites/<contributor>/<slug>.json).
  • Links prerequisite generic skills and attaches named suite components atomically.
  • Skips documentation rebuild by default. Pass --build to regenerate artifacts.
Flag Description Default
<generic-id> Starless generic skill ID to create or update (e.g. get-shit-done). required
--name <name> Human-readable display name (required if creating). —
--description <desc> Description text (≥10 characters; required if creating). —
--prereqs <ids> Comma-separated list of prerequisite generic skill IDs. —
--named-capstone <contributor/slug> Existing named capstone skill to associate with this fusion. —
--suite-components <ids> Comma-separated named skill IDs to persist into the suite manifest. —
--build Rebuild site documentation after fusing. false
examples
# Create a fusion node and wire suite components
GAIA_OPERATOR_OVERRIDE=1 gaia dev fuse get-shit-done \
  --name "Get Shit Done" \
  --description "Autonomous execution workflow combining multiple tools" \
  --prereqs planning,execution \
  --named-capstone gsd-build/get-shit-done \
  --suite-components gsd-build/planning,gsd-build/execution
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 rm <skill-id> [--reason <text>] [--yes] [--build] ◇ verifier
  • Removes a generic skill node or a Named Skill (contributor/slug) from the registry.
  • Cleans up prerequisite and derivative links across adjacent nodes automatically.
  • Logs a removal timeline event. For named skills, --reason is recorded in the timeline.
Flag Description Default
<skill-id> Generic or named skill ID to remove. required
--reason <text> Human-readable reason for removal logged to the timeline. —
--yes, -y Skip interactive confirmation prompt. false
--build Rebuild site documentation after removing the skill. false
examples
# Remove a deprecated named skill
GAIA_OPERATOR_OVERRIDE=1 gaia dev rm contributor/old-skill --reason "Replaced by new upstream suite" --yes
gaia dev reclassify <skill-id> {basic,fusion} [--build] ◇ verifier
  • Changes the structural type of a generic skill node between basic (0 prerequisites) and fusion (≥1 prerequisite).
  • Moves the underlying JSON file between registry/nodes/basic/ and registry/nodes/fusion/.
  • Updates all referencing metadata and logs a reclassification event.
Flag Description Default
<skill-id> Generic skill ID to reclassify. required
{basic,fusion} New structural type under Yggdrasil II taxonomy. required
--build Rebuild site documentation after reclassifying. false
examples
GAIA_OPERATOR_OVERRIDE=1 gaia dev reclassify data-pipeline fusion
gaia dev update-named <skill-id> [options] [--build] ◇ verifier
  • Updates frontmatter properties of an existing Named Skill (registry/named/<contributor>/<slug>.md).
  • Supports updating title, status, genericRef, suiteRef, suiteComponents, origin, github-link, and installable flags.
  • Logs an update timeline event automatically.
Flag Description Default
<skill-id> Named skill ID (e.g. contributor/skill-name). required
--title <title> Display lore title for the named skill. —
--status <status> Lifecycle status (awakened, named, etc.). —
--generic-ref <id> Generic skill reference ID fulfilled by this implementation. —
--github-link <url> GitHub source link (must be a blob/ link for 3★+). —
--origin {true,false} Set whether this implementation is the canonical Origin. —
--installable {true,false} Set installability status in share bundles and manifests. —
--build Rebuild site documentation and indexes after updating. false
examples
# Update generic reference and origin flag
GAIA_OPERATOR_OVERRIDE=1 gaia dev update-named karpathy/web-scrape --generic-ref web-scrape --origin true
gaia dev timeline <skillId> --user <handle> --action <action> [--notes <text>] [--timestamp <ISO8601>] [--previous-value <level>] [--new-value <level>] ◇ verifier
  • Appends a timeline action to a skill's log.
  • Requires the --user flag to write to user skill tree files.
  • Supports historical timestamps; events are sorted chronologically.
  • With --user, --previous-value and --new-value are recorded on the event. For rank_up or demote, --new-value also updates a matching unlockedSkills level and appends to levelHistory; it does not create a missing entry.
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, note. —
--notes <text> Human-readable description appended to the event. —
--timestamp <ISO8601> Historical timestamp. Backfilled events are sorted chronologically. now (UTC)
--previous-value <level> Previous level (e.g. 1★) recorded on the event when --user is supplied. —
--new-value <level> New level (e.g. 3★) recorded when --user is supplied. For rank_up/demote, also updates a matching unlockedSkills level and appends a levelHistory entry. —
examples
# Append a current-time event to alice's tree
GAIA_OPERATOR_OVERRIDE=1 gaia dev timeline web-search \
  --user alice --action rank_up --previous-value 1★ --new-value 3★ \
  --notes "Promoted to 3★ Evolved"

# Record historical context without changing the rank
GAIA_OPERATOR_OVERRIDE=1 gaia dev timeline web-search \
  --user alice --action note --timestamp 2026-01-15T00:00:00Z \
  --notes "Historical context"

# Record a historical rank change and update a matching unlockedSkills entry
GAIA_OPERATOR_OVERRIDE=1 gaia dev timeline web-search \
  --user alice --action rank_up --previous-value 1★ --new-value 3★ \
  --timestamp 2026-01-15T00:00:00Z --notes "Historical rank change"
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 [ref] [--base <base-ref>] ● open
  • Shows substantive registry additions and modifications in a branch compared to main.
  • Strips generated artifact noise (Class S rebuilds, timestamps) to surface real content changes.
  • Short branch names automatically resolve with origin/ prefix.
Flag Description Default
[ref] Branch or ref to compare against the base. HEAD
--base <base-ref> Base git ref to compare against. origin/main
examples
# Compare current branch against origin/main
gaia dev diff

# Compare a review branch against main
gaia dev diff review/meta/intake-batch-42
gaia dev arbor {import, check, replay} [input] ◇ verifier
  • Manages declaration-first Arbor sidecar records and benchmark receipts.
  • Supports immutable record import, schema and profile validation, and deterministic profile replay.
Subcommand / Flag Description Default
import <file.json> Validate and immutably import a declaration or benchmark receipt JSON file. required
check [file.json] Validate one record or the complete Arbor source/profile store if omitted. all store
replay Recompute generated Arbor profiles deterministically from immutable sources. —
examples
# Check Arbor store integrity
gaia dev arbor check

# Import a benchmark receipt
GAIA_OPERATOR_OVERRIDE=1 gaia dev arbor import receipts/gaia-benchmark-run-01.json
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"
gaia dev build ◇ verifier
  • Compiles all Class S site-served artifacts, visual graphs, and registry indexes across the repository.
  • Regenerates docs/graph/gaia.json, docs/graph/gaia.gexf, docs/graph/gaia.svg, docs/graph/named/index.json, and registry/named-skills.json.
  • Essential step after running batched gaia dev operations without individual rebuilds.
examples
GAIA_OPERATOR_OVERRIDE=1 gaia dev build

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 →