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 devcommands.
Local-first notes:
- Commands show your personal skills, scan candidates, and local files.
- Use the
--canonflag to query the main registry instead.
Table of Contents
Player Workflow
Discovery
System & Sharing
Registry Dev
dev add— Add nodedev evidence— Add evidencedev rm-evidence— Remove evidencedev verify— Verify/dispute evidencedev calibrate— Set star leveldev calibrate-evidence-grades— Backfill evidence gradesdev calibrate-trust-magnitude— Refresh Trust Magnitude cachedev fuse— Create fusion nodedev merge— Merge nodesdev split— Split nodedev rename— Rename a skilldev rm— Remove a skilldev link— Link prerequisite edgesdev reclassify— Reclassify structural typedev update-named— Update named frontmatterdev timeline— Add timeline logdev timeline-resort— Re-sort timelinedev prefill— Prefill a discovery packetdev assess— Assess a packetdev ratify— Ratify a packet (L4)dev embed— Build skill embeddingsdev evidence-seed— Seed evidence for an approved skilldev provenance— Write a provenance ledgerdev verify-tier— Recompute verification tierdev list— Query registrydev audit— Run registry linterdev diff— Diff registry vs maindev arbor— Arbor sidecar storedev sync-upstream— Upstream trackingdev freeze— Freeze skilldev build— Compile registry & docs- Global Flags
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.tomlconfiguration 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.mdfiles 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-onlyflag.
| 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
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.htmlby 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/mcpwas 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
--versionglobal 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 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
.jsonfile path or anhttps://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 acontributor/slugform: installs a single named skill into.agents/skills/(equivalent togaia 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
--yesis provided. - Skips documentation rebuild by default. Pass
--buildto 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
--buildto 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_upordemotetimeline 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, andtrustMagnitudeInputHashfrontmatter 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
--buildto 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/derivativesin other nodes,genericSkillRefandsuiteComponents/suiteRefin 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
renametimeline event automatically. No separategaia dev timelinecall needed. - Fails if
new-idalready 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,
--reasonis 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 link
<target> <prereqs> [--reset] [--build]
◇ verifier
- Links skills together in the DAG by adding prerequisite edges to the target node.
- Pass
--resetto replace all existing prerequisites instead of appending. - Checks for circular dependencies before writing changes.
| Flag | Description | Default |
|---|---|---|
| <target> | Target skill ID receiving prerequisite edges. | required |
| <prereqs> | Comma-separated list of prerequisite skill IDs. | required |
| --reset | Overwrite existing prerequisites instead of appending. | false |
| --build | Rebuild site documentation after updating links. | false |
examples
# Link web-scrape to require browser-driver and html-parser GAIA_OPERATOR_OVERRIDE=1 gaia dev link web-scrape browser-driver,html-parser
gaia dev reclassify
<skill-id> {basic,fusion} [--build]
◇ verifier
- Changes the structural type of a generic skill node between
basic(0 prerequisites) andfusion(≥1 prerequisite). - Moves the underlying JSON file between
registry/nodes/basic/andregistry/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
--userflag to write to user skill tree files. - Supports historical timestamps; events are sorted chronologically.
- With
--user,--previous-valueand--new-valueare recorded on the event. Forrank_upordemote,--new-valuealso updates a matchingunlockedSkillslevel and appends tolevelHistory; 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
timelinein 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 timelineonly appends. - Skips the docs rebuild by default. Pass
--buildto 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 withdev embedfirst. - Suite fan-outs use
--suite-role,--suite-idand--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 offis the default; semantic principles stayunknown.liveadds 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
l4Resolutionblock to the packet and sets it to review-ready. The packet then goes togaia push --from-file. - Pre-flight checks run before any write. One failed check writes nothing.
--assessmenttakes the principles receipt from the prefill step. The receipt proves it is fresh, not that its semantics are right.--contributormust be lowercase. Mixed-case input is rejected.--generic-name,--generic-description,--generic-type, and--prereqsare optional forMAP, which reads them from the live node.NEW_GENERICrequires the name, description, and type. It requires--prereqsonly for afusiongeneric; abasicgeneric must have none.--skill-file-urldefaults 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 indexdev prefillsearches. --checkonly reports whether the file is fresh.--forcerebuilds 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.
--sourcerepeats.--no-collectorswrites 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-eventlogs a pre-ingest event.dev timelinecannot, because no node exists yet.--statusdefaults toingested.
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,securityorenterprise. - 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_syncedevent 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: falsein a named skill's frontmatter. - Appends an
upstream_deprecatedevent 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, andregistry/named-skills.json. - Essential step after running batched
gaia devoperations 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. |