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

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, create a custom fusion path, edit an existing one, or delete one.
  • 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, full} [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. —
full run [--observe | --triage | --verify | --retro] [--routine N] [--debt ID] [--resume RUN] [--afk] [--trigger {manual,scheduled}] [--no-agents] [--integration-branch B] [--push] [--ledger {auto,git,local}] [--json] Run or resume the deterministic pipeline. Observation, triage, verification, and retro modes narrow the phases; --no-agents never dispatches Class B work. Actions needing a model or forge are emitted for a driver. Never merges or pushes to main. —
full record RUN_ID STEP_ID --input FILE.json [--ledger {auto,git,local}] [--json] Record a driver's outcome for an action emitted by full run. Routine 19 success-shaped outcomes require matching shared operation/head/evidence; local outcome JSON is not settlement authority. —
full abandon RUN_ID --reason TEXT [--ledger {auto,git,local}] [--json] End an open run with an auditable reason. Pending actions are superseded, and unbuilt work stays adoptable by a later run. —
full status [--ledger {auto,git,local}] [--json] Read-only view of the ledger and active run. —
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"

# Run the resumable pipeline in observation-only mode
gaia steward full run --observe

# Abandon an open run with an audit reason
gaia steward full abandon RUN_ID --reason "operator stopped the run"

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. Requires --contributor and --generic-ref. false
--contributor <handle> Contributor handle for the named skill. Must be lowercase — mixed-case input is rejected. gaiabot
--generic-ref <id> Generic skill ID this named skill implements. —
--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/).
⚠️ --contributor must be lowercase. A mixed-case handle (e.g. Marco) is rejected — use the handle's lowercase form (marco). Case is otherwise preserved; two contributors who differ only by case are treated as a collision, not two directories.
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 named skill implementing an existing generic node
GAIA_OPERATOR_OVERRIDE=1 gaia dev add "Structured Output" \
  --named --contributor marco --generic-ref structured-output --description "Reliably emits JSON 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. Stored as typed; the CLI does not check it against the contributor registry. 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). Stored as typed; the CLI does not check it against the contributor registry. —
--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 timeline-resort <contributor/slug> [--dry-run] [--build] ◇ verifier
  • Puts one named skill's timeline in ascending UTC order.
  • Order only. It never adds, removes, or edits an event, and it checks that before it writes.
  • Use it when a hand-written event sits out of order. dev timeline only appends.
  • Skips the docs rebuild by default. Pass --build to regenerate.
examples
# Preview the current and proposed order
gaia dev timeline-resort alice/web-search --dry-run

# Apply it
GAIA_OPERATOR_OVERRIDE=1 gaia dev timeline-resort alice/web-search
gaia dev prefill <candidate-id> --name <n> --description <d> --url <url> [--vector <file>] [--allow-stale] [--json] ● open
  • Builds a discovery packet for one candidate skill and maps it to the closest generic skills by embedding similarity.
  • Writes the packet to disk, or prints it with --json.
  • Refuses a stale embeddings file unless you pass --allow-stale. Refresh it with dev embed first.
  • Suite fan-outs use --suite-role, --suite-id and --component-ids.
example
gaia dev prefill alice/web-search --name "Web Search" --description "Search the web and cite sources" --url https://github.com/alice/skills/blob/main/web-search/SKILL.md
gaia dev assess <packet-path> [--output <path>] [--jev {off,offline,live}] ● open
  • Checks a discovery packet against the curation principles and writes an advisory receipt.
  • The receipt binds the candidate, the source bytes and the live generic catalog. It proves the packet is fresh, not that the mapping is right.
  • --jev off is the default; semantic principles stay unknown. live adds cached, budget-bounded Jev advice.
example
gaia dev assess registry-for-review/discovery-packets/alice-web-search-*.json
gaia dev ratify <packet> --decision {MAP,NEW_GENERIC} --generic-id <id> --contributor <handle> --skill-name <name> --assessment <receipt> --reviewed-by <who> --approval-ref <ref> --reason <text> ◇ verifier
  • The L4 human-review step for a discovery packet. It records who approved a candidate and why.
  • Writes a l4Resolution block to the packet and sets it to review-ready. The packet then goes to gaia push --from-file.
  • Pre-flight checks run before any write. One failed check writes nothing.
  • --assessment takes the principles receipt from the prefill step. The receipt proves it is fresh, not that its semantics are right.
  • --contributor must be lowercase. Mixed-case input is rejected.
  • --generic-name, --generic-description, --generic-type, and --prereqs are optional for MAP, which reads them from the live node. NEW_GENERIC requires the name, description, and type. It requires --prereqs only for a fusion generic; a basic generic must have none.
  • --skill-file-url defaults to the packet's source URL. Without --acknowledge-human-review, the write is rejected. Pass it only after a person has reviewed the candidate.
⚠️ Operator access is not approval. GAIA_OPERATOR_OVERRIDE=1 lets the command run. It does not count as L4 approval. Only a named human reviewer may record --reviewed-by, --approval-ref, and --reason.
example
# Map a candidate to an existing generic skill, after human review
GAIA_OPERATOR_OVERRIDE=1 gaia dev ratify registry-for-review/discovery-packets/marco-web-search-*.json \
  --decision MAP --generic-id web-search --contributor marco --skill-name web-search \
  --assessment generated-output/curation/marco-web-search-*.assessment.json --reviewed-by marco --approval-ref "https://github.com/gaia-research/gaia-skill-tree/issues/1234" \
  --reason "Matches the generic web-search node" --acknowledge-human-review
gaia dev embed [--model <model>] [--force] [--check] [--output <path>] ● open
  • Generates registry/embeddings.json, the index dev prefill searches.
  • --check only reports whether the file is fresh. --force rebuilds it anyway.
example
gaia dev embed --check
gaia dev evidence-seed <skill-id> [--source url::type[::scope]] [--scope {standalone,suite-component,suite-wide}] [--no-collectors] ● open
  • Writes a per-type seed under evidence/seeds/ for an L4-approved skill, plus collector rows.
  • Takes raw sources only. Stars, grades and tiers are computed later, never supplied here.
  • --source repeats. --no-collectors writes the seed file alone.
example
gaia dev evidence-seed alice/web-search --source https://github.com/alice/skills::repo-own
gaia dev provenance <skill-id> [--from-packet <file>] [--generic-ref <id>] [--status <status>] [--stage-event {discovered,intake_opened}] ● open
  • Writes registry/provenance/<skill-id>.json, linking a node back to its packet, intake batch, issue and evidence seed.
  • --stage-event logs a pre-ingest event. dev timeline cannot, because no node exists yet.
  • --status defaults to ingested.
example
gaia dev provenance alice/web-search --from-packet packet.json --generic-ref web-search
gaia dev verify-tier <skill-id> ● open
  • Recomputes a skill's verification tier: community, benchmark, security or enterprise.
  • Takes a generic id or a contributor/slug.
example
gaia dev verify-tier alice/web-search
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 →