CLI Reference#
This page contains the auto-generated documentation for the metagit command-line interface.
metagit#
Metagit CLI: A multi-purpose CLI tool with YAML configuration.
Usage:
metagit [OPTIONS] [COMMAND] [ARGS]...
Options:
--version Show the version and exit.
-c, --config TEXT Path to the configuration file
--debug / --no-debug Enable or disable debug mode
--verbose / --no-verbose Enable or disable verbose output
-h, --help Show this message and exit.
agent#
Export and install bundled agent definitions for coding vendors.
Usage:
metagit agent [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
apply#
Materialize merged agent_profile blocks into vendor runtimes.
Usage:
metagit agent apply [OPTIONS]
Options:
--vendor [opencode|hermes|openclaw|claude_code|cursor|github_copilot|windsurf|codex]
Vendor runtime to materialize profiles into.
[required]
-p, --project TEXT Limit to one workspace project.
-n, --repo TEXT Limit to one repository within --project.
--tag TEXT Filter targets by inherited tag, e.g. --tag
agent_tier=full
--root PATH Manifest root containing `.metagit.yml`.
[default: .]
--scope [project|user] Install scope for skills and MCP artifacts.
[default: project]
--dry-run Print the apply plan without writing files.
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
create#
Install an agent definition into a vendor-specific agents directory.
Usage:
metagit agent create [OPTIONS] TEMPLATE_ID
Options:
--vendor, --target [opencode|hermes|openclaw|claude_code|cursor|github_copilot|windsurf|codex]
Coding vendor to install for (auto-detect
when omitted).
--scope [project|user] Install to project-local or user-global
vendor config. [default: project]
--project-root DIRECTORY Workspace coordinator root (for project
scope paths). [default: .]
--root PATH Manifest root for workspace template
overlays.
--answers-file FILE YAML/JSON mapping of template variables.
--no-prompt Use defaults only; fail if required.
--force Overwrite an existing agent definition.
--dry-run Show actions without writing files.
--install-skills Install template recommended_skills for the
selected vendor.
--install-mcp Install metagit MCP server config for the
selected vendor.
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
dispatch-plan#
Build install, launch, and handoff envelope for subagent dispatch.
Usage:
metagit agent dispatch-plan [OPTIONS] TEMPLATE_ID
Options:
--vendor [opencode|hermes|openclaw|claude_code|cursor|github_copilot|windsurf|codex]
Vendor runtime to target for install and
launch hints. [default: claude_code]
-p, --project TEXT Workspace project name for repo- or project-
scoped dispatch.
-n, --repo TEXT Repository name within --project.
--root PATH Manifest root containing `.metagit.yml`.
[default: .]
--scope [project|user] Install scope when checking or suggesting
`agent create`. [default: project]
--task TEXT Short task summary for launch hints.
-c, --definition TEXT Path to workspace definition (for handoff
CLI commands). [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
export#
Export a template to files (vendor-neutral layout).
Usage:
metagit agent export [OPTIONS] TEMPLATE_ID
Options:
-o, --output DIRECTORY Directory to write rendered template files.
[default: .]
--root PATH Manifest root for workspace template overlays.
--answers-file FILE YAML/JSON mapping of template variables.
--no-prompt Use defaults only; fail if required.
--force Overwrite existing output files.
--dry-run Render without writing files.
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
list#
List bundled agent templates.
Usage:
metagit agent list [OPTIONS]
Options:
--json Emit machine-readable JSON.
--root PATH Manifest root for workspace template overlays.
-h, --help Show this message and exit.
overlay#
Workspace overlay templates under .metagit/.agent-templates/.
Usage:
metagit agent overlay [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
init#
Scaffold an editable overlay from a bundled agent template.
Usage:
metagit agent overlay init [OPTIONS] TEMPLATE_ID
Options:
--root PATH Manifest root containing `.metagit.yml`. [default:
.]
--mode [minimal|full] minimal copies manifest stub + body; full copies all
bundled sources. [default: full]
--local Write to gitignored `.metagit/.agent-templates/`
(personal override).
--force Replace an existing overlay directory.
--dry-run Show files that would be written.
--open / --no-open Open the primary overlay file in $EDITOR after
scaffolding.
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
path#
Print committed and local overlay directories for a template id.
Usage:
metagit agent overlay path [OPTIONS] TEMPLATE_ID
Options:
--root PATH Manifest root containing `.metagit.yml`. [default: .]
-h, --help Show this message and exit.
preview#
Render a vendor artifact without writing files.
Usage:
metagit agent preview [OPTIONS] TEMPLATE_ID
Options:
--vendor [opencode|hermes|openclaw|claude_code|cursor|github_copilot|windsurf|codex]
Vendor artifact to render. [default:
claude_code]
--root PATH Manifest root for overlays and prompt
defaults. [default: .]
--answers-file FILE YAML/JSON mapping of template variables.
--no-prompt Use defaults only; fail if required.
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
profile#
Inspect and validate agent_profile blocks in the manifest.
Usage:
metagit agent profile [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
show#
Print the fully merged effective agent profile for one repo.
Usage:
metagit agent profile show [OPTIONS]
Options:
-p, --project TEXT Workspace project name. [required]
-n, --repo TEXT Repository name within --project. [required]
--root PATH Manifest root containing `.metagit.yml`. [default: .]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
schema#
Write the agent template manifest JSON Schema.
Usage:
metagit agent schema [OPTIONS]
Options:
--output-path FILE Write JSON Schema to this path. [default:
./schemas/agent_template.schema.json]
-h, --help Show this message and exit.
show#
Show one agent template manifest.
Usage:
metagit agent show [OPTIONS] TEMPLATE_ID
Options:
--json Emit machine-readable JSON.
--root PATH Manifest root for workspace template overlays.
-h, --help Show this message and exit.
validate#
Validate agent template manifests and template files.
Usage:
metagit agent validate [OPTIONS]
Options:
--template TEXT Validate one template id (default: all bundled + overlays).
--root PATH Manifest root for workspace template overlays.
-h, --help Show this message and exit.
aos#
Agent Operating System composition façade (RFC-0013).
Usage:
metagit aos [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
doctor#
Report coordination health; optionally run safe ACL GC.
Usage:
metagit aos doctor [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--fix Run safe ACL GC (requires --yes)
--yes Confirm --fix mutations
--json
-h, --help Show this message and exit.
heartbeat#
Renew active ACL leases for an agent.
Usage:
metagit aos heartbeat [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--agent-id TEXT [required]
--ttl TEXT [default: 1h]
--json
-h, --help Show this message and exit.
next#
Preview or commit the next composed work envelope.
Usage:
metagit aos next [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--graph-id TEXT
--commit Record schedule decision
--apply-hints Apply ACL bind APIs for the chosen node
--agent-id TEXT Required with --apply-hints
--json
-h, --help Show this message and exit.
recover#
Safe agent-scoped recovery (requires --yes).
Usage:
metagit aos recover [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--agent-id TEXT [required]
--yes Confirm recovery mutations
--release-orphan-claims
--cancel-stale-merges
--json
-h, --help Show this message and exit.
status#
Show aggregated coordination subsystem status.
Usage:
metagit aos status [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--json
-h, --help Show this message and exit.
aos#
Agent Operating System composition façade (RFC-0013).
Usage:
metagit aos [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
doctor#
Report coordination health; optionally run safe ACL GC.
Usage:
metagit aos doctor [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--fix Run safe ACL GC (requires --yes)
--yes Confirm --fix mutations
--json
-h, --help Show this message and exit.
heartbeat#
Renew active ACL leases for an agent.
Usage:
metagit aos heartbeat [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--agent-id TEXT [required]
--ttl TEXT [default: 1h]
--json
-h, --help Show this message and exit.
next#
Preview or commit the next composed work envelope.
Usage:
metagit aos next [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--graph-id TEXT
--commit Record schedule decision
--apply-hints Apply ACL bind APIs for the chosen node
--agent-id TEXT Required with --apply-hints
--json
-h, --help Show this message and exit.
recover#
Safe agent-scoped recovery (requires --yes).
Usage:
metagit aos recover [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--agent-id TEXT [required]
--yes Confirm recovery mutations
--release-orphan-claims
--cancel-stale-merges
--json
-h, --help Show this message and exit.
status#
Show aggregated coordination subsystem status.
Usage:
metagit aos status [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--json
-h, --help Show this message and exit.
api#
Local JSON API commands.
Usage:
metagit api [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
serve#
Serve managed-repo search JSON endpoints on localhost.
Usage:
metagit api serve [OPTIONS]
Options:
--root TEXT Workspace root containing `.metagit.yml`. [default: .]
--host TEXT [default: 127.0.0.1]
--port INTEGER [default: 7878]
--status-once Bind once, print ready line with resolved port, and exit.
-h, --help Show this message and exit.
appconfig#
Application configuration subcommands
Usage:
metagit appconfig [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
create#
Create default application config
Usage:
metagit appconfig create [OPTIONS]
Options:
--config-path TEXT Path to save configuration file (default:
~/.config/metagit/config.yml).
-h, --help Show this message and exit.
get#
Get a value from the application configuration.
Example - show all keys in the providers section:
metagit appconfig get --name config.providers --show-keys
Example - show all values in the providers section:
metagit appconfig get --name config.providers
Usage:
metagit appconfig get [OPTIONS]
Options:
--name TEXT Appconfig element to target
--show-keys If the element is a dictionary, show all key names. If it is
a list, show all name attributes
--output TEXT Output format (json/yaml)
-h, --help Show this message and exit.
info#
Information about the application configuration.
Usage:
metagit appconfig info [OPTIONS]
Options:
-h, --help Show this message and exit.
patch#
Apply schema operations to metagit.config.yaml (enable/disable/set/append/remove).
Paths use AppConfig field names (e.g. workspace.dedupe.enabled), not the config: wrapper.
Usage:
metagit appconfig patch [OPTIONS]
Options:
--file FILE JSON file with operations array or
{operations, save}
--op [enable|disable|set|append|remove]
Single operation kind (use with --path)
--path TEXT Field path for a single operation
--value TEXT Value for set (JSON or scalar)
--save Write changes to disk when validation passes
--no-format Skip schema-ordered YAML formatting when
saving
--tree Include updated schema tree in JSON output
--json Print JSON for agents
-h, --help Show this message and exit.
preview#
Preview app config after draft operations (secrets redacted in output).
Usage:
metagit appconfig preview [OPTIONS]
Options:
--style [normalized|minimal|disk]
YAML preview style [default: normalized]
--file FILE JSON file with operations array or
{operations, save}
--op [enable|disable|set|append|remove]
Single operation kind (use with --path)
--path TEXT Field path for a single operation
--value TEXT Value for set (JSON or scalar)
--output TEXT Write preview YAML to this path instead of
stdout
--json Print JSON for agents
-h, --help Show this message and exit.
schema#
Generate a JSON schema for the AppConfig class and write it to a file.
Usage:
metagit appconfig schema [OPTIONS]
Options:
--output-path TEXT Path to output the JSON schema file
-h, --help Show this message and exit.
set#
Set a value in the application configuration.
Usage:
metagit appconfig set [OPTIONS]
Options:
--name TEXT Appconfig element to target
--value TEXT Value to set
-h, --help Show this message and exit.
show#
Show the full active application configuration.
Usage:
metagit appconfig show [OPTIONS]
Options:
-f, --format [yaml|json|minimal-yaml]
Output format (yaml=full active config,
json=agents, minimal-yaml=non-default only)
[default: yaml]
-h, --help Show this message and exit.
tree#
Show schema-backed field tree for metagit.config.yaml.
Usage:
metagit appconfig tree [OPTIONS]
Options:
--json Print JSON for agents
-h, --help Show this message and exit.
validate#
Validate a configuration file
Usage:
metagit appconfig validate [OPTIONS]
Options:
--config-path TEXT Path to the configuration file
-h, --help Show this message and exit.
atlas#
Manage repository-local Metagit Atlas artifacts.
Usage:
metagit atlas [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
generate#
Generate deterministic Atlas evidence artifacts.
Usage:
metagit atlas generate [OPTIONS]
Options:
--path TEXT [default: .]
--json
-h, --help Show this message and exit.
init#
Initialize the local Atlas layout.
Usage:
metagit atlas init [OPTIONS]
Options:
--path TEXT [default: .]
--generate Run generate after init
--repository TEXT Repository identity for atlas.yaml
--json
-h, --help Show this message and exit.
query#
Query local Atlas entities with a minimal DSL expression.
Usage:
metagit atlas query [OPTIONS] EXPRESSION
Options:
--path TEXT [default: .]
--json
-h, --help Show this message and exit.
refresh#
Refresh Atlas evidence after source changes.
Usage:
metagit atlas refresh [OPTIONS] [PATHS]...
Options:
--path TEXT [default: .]
--json
-h, --help Show this message and exit.
status#
Show Atlas initialization, generation, and freshness status.
Usage:
metagit atlas status [OPTIONS]
Options:
--path TEXT [default: .]
--json
-h, --help Show this message and exit.
validate#
Validate Atlas configuration and curated entity references.
Usage:
metagit atlas validate [OPTIONS]
Options:
--path TEXT [default: .]
--json
-h, --help Show this message and exit.
branch#
Manage agent/* branch allocations (ACL).
Usage:
metagit branch [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
allocate#
Allocate a unique agent/* branch.
Usage:
metagit branch allocate [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT project/repo, or . / self for the definition repo
[required]
--agent-id TEXT [required]
--task-id TEXT [required]
--description TEXT Optional short branch suffix
--name TEXT Explicit branch name; must match
coordination.allowed_branch_prefixes (default
agent/)
--base TEXT Base ref/commit for the new branch
--integration-branch TEXT
--no-git Record allocation without creating a git branch
--json
-h, --help Show this message and exit.
archive#
Archive a branch allocation record.
Usage:
metagit branch archive [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--branch-id TEXT
--name TEXT
--repository TEXT
--json
-h, --help Show this message and exit.
cleanup#
Delete released/archived branches with no active lease or worktree.
Usage:
metagit branch cleanup [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--no-delete-git Keep local git branches
--json
-h, --help Show this message and exit.
list#
List branch allocations.
Usage:
metagit branch list [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT
--status TEXT
--json
-h, --help Show this message and exit.
release#
Mark a branch allocation as released.
Usage:
metagit branch release [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--branch-id TEXT
--name TEXT
--repository TEXT
--json
-h, --help Show this message and exit.
campaign#
Manage cross-project campaign overlays (default directory: _campaigns/).
Usage:
metagit campaign [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
board-sync#
Create or refresh Azure DevOps work items for a campaign (paged).
Usage:
metagit campaign board-sync [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--provider [azure_devops] [default: azure_devops]
--organization TEXT ADO organization (or
METAGIT_AZURE_DEVOPS_ORGANIZATION).
--ado-project TEXT ADO project (or METAGIT_AZURE_DEVOPS_PROJECT).
--parent-type TEXT [default: Feature]
--child-type TEXT [default: User Story]
--limit INTEGER Max child work items to create this call.
[default: 40]
--offset INTEGER [default: 0]
--dry-run Report what would be created without calling ADO.
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
context#
Assemble provenance-aware campaign context from MetaGit and optional EverRoom.
Usage:
metagit campaign context [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--include [summary|repositories|relationships|git_state|instructions|decisions|open_questions|documents|sources|knowledge]
Context sections to include (repeatable).
Default is a concise packet.
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
everroom#
Optional EverRoom Room association for a campaign.
Usage:
metagit campaign everroom [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
attach#
Associate an existing EverRoom Room with a campaign.
Usage:
metagit campaign everroom attach [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--room TEXT EverRoom Room id (not the campaign slug). [required]
--endpoint TEXT Override EverRoom Gateway base URL.
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
create#
Create a derived EverRoom Room from campaign metadata and attach it.
Usage:
metagit campaign everroom create [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--endpoint TEXT Override EverRoom Gateway base URL.
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
detach#
Remove the EverRoom association. The remote Room is not deleted.
Usage:
metagit campaign everroom detach [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
status#
Show EverRoom connection and Room association for a campaign.
Usage:
metagit campaign everroom status [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
sync#
Project MetaGit campaign state into a generated EverRoom document.
Usage:
metagit campaign everroom sync [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
expand#
Generate one spine objective per matching campaign repo (paged).
Usage:
metagit campaign expand [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--tag TEXT Optional tag filter for expansion.
--dry-run Show objective ids without writing.
--limit INTEGER Max objectives to create this call. Page with --offset.
[default: 40]
--offset INTEGER [default: 0]
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
list#
List campaigns with rollup counts.
Usage:
metagit campaign list [OPTIONS]
Options:
--definition TEXT Path to the Metagit workspace definition file [default:
.metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
new#
Create a campaign by resolving repos from a query or an explicit --repo list.
Usage:
metagit campaign new [OPTIONS]
Options:
--slug TEXT Campaign slug (filename stem). [required]
--title TEXT Human-readable campaign title. [required]
--query TEXT Repository selection query (metagit find syntax).
Provide this or --repo.
--repo TEXT Explicit project/repo to include (repeatable). Freezes
the repo set (no query drift).
--tag TEXT Optional tag filter during selection.
--goal TEXT Free-text objective describing what the campaign
delivers.
--reference TEXT Exemplar repo (project/repo) to model changes on.
--objective-id TEXT Optional spine objective id to bind.
--work-item TEXT Parent board ref (azure_devops:123 or URL).
--work-item-url TEXT Browser URL for the parent work item.
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
set#
Update one campaign repo entry.
Usage:
metagit campaign set [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--repo TEXT Repo selector as project/repo. [required]
--status [pending|routed|mr-open|merged|blocked]
[required]
--mr TEXT Merge request URL.
--note TEXT Status note.
--work-item TEXT Board ref for this repo (azure_devops:123 or
URL).
--work-item-url TEXT Browser URL for the repo work item.
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
status#
Show campaign status with a paged repo window (not the full overlay).
Usage:
metagit campaign status [OPTIONS]
Options:
--slug TEXT Campaign slug. [required]
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
--limit INTEGER Max repo rows to include (JSON and human).
Use 0 for counts-only. [default: 40]
--offset INTEGER [default: 0]
--repo-status [pending|routed|mr-open|merged|blocked]
Filter the paged repo window by status.
--include-repos / --no-repos Include a paged repo window. Counts are
always returned. [default: include-repos]
-h, --help Show this message and exit.
validate#
Validate every campaign document and atlas repo references.
Usage:
metagit campaign validate [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
-h, --help Show this message and exit.
claim#
Manage advisory file-path claims.
Usage:
metagit claim [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
check#
Check for overlapping advisory claims.
Usage:
metagit claim check [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT project/repo, or . / self for the definition repo
[required]
--pattern TEXT
--component TEXT Catalogued component name; defaults patterns to its path
--agent-id TEXT Ignore this agent's own claims
--json
-h, --help Show this message and exit.
declare#
Declare advisory file claims before coding.
Usage:
metagit claim declare [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT project/repo, or . / self for the definition repo
[required]
--agent-id TEXT [required]
--pattern TEXT
--component TEXT Catalogued component name; defaults patterns to its path
--task-id TEXT
--strict Fail when overlapping claims exist
--json
-h, --help Show this message and exit.
list#
List file claims.
Usage:
metagit claim list [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT
--agent-id TEXT
--status TEXT
--json
-h, --help Show this message and exit.
release#
Release an advisory file claim.
Usage:
metagit claim release [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--claim-id TEXT [required]
--agent-id TEXT [required]
--force
--json
-h, --help Show this message and exit.
completion#
Generate and install shell tab completion for metagit.
Usage:
metagit completion [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
doctor#
Verify that the installed metagit binary supports completion callbacks.
Usage:
metagit completion doctor [OPTIONS]
Options:
-h, --help Show this message and exit.
install#
Install a user-level completion script or print activation instructions.
Usage:
metagit completion install [OPTIONS]
Options:
-s, --shell [zsh|bash|fish] Target shell (zsh, bash, fish) [required]
--path FILE Write the completion script to this file
(default: OS convention)
--stdout Print eval/source instructions instead of
writing a file
-h, --help Show this message and exit.
show#
Print a completion script to stdout.
Usage:
metagit completion show [OPTIONS]
Options:
-s, --shell [zsh|bash|fish] Target shell (zsh, bash, fish) [required]
-h, --help Show this message and exit.
component#
List, show, resolve, graph, detect, and init catalogued components.
Usage:
metagit component [OPTIONS] COMMAND [ARGS]...
Options:
-c, --config-path TEXT Path to the metagit configuration file
-h, --help Show this message and exit.
detect#
Run component detect for filesystem marker candidates (read-only without --apply).
Usage:
metagit component detect [OPTIONS]
Options:
-c, --config-path TEXT Path to the metagit configuration file
--project TEXT
--repo TEXT
--apply
--json
-h, --help Show this message and exit.
graph#
Run component graph neighborhood walk from a catalog identity.
Usage:
metagit component graph [OPTIONS] IDENTITY
Options:
-c, --config-path TEXT Path to the metagit configuration file
--project TEXT
--repo TEXT
--depth INTEGER
--direction [out|in|both]
--json
-h, --help Show this message and exit.
init#
Run component init for one declarative repository-relative path.
Usage:
metagit component init [OPTIONS] PATH
Options:
-c, --config-path TEXT Path to the metagit configuration file
--name TEXT
--kind TEXT
--project TEXT
--repo TEXT
--apply
--json
-h, --help Show this message and exit.
list#
List catalogued components, optionally filtered by project/repo.
Usage:
metagit component list [OPTIONS]
Options:
-c, --config-path TEXT Path to the metagit configuration file
--project TEXT
--repo TEXT
--json
-h, --help Show this message and exit.
resolve#
Run component resolve for a path to the longest-matching catalogued component.
Usage:
metagit component resolve [OPTIONS] PATH
Options:
-c, --config-path TEXT Path to the metagit configuration file
--project TEXT
--repo TEXT
--json
-h, --help Show this message and exit.
show#
Show one component by project/repo/component id or unique name.
Usage:
metagit component show [OPTIONS] IDENTITY
Options:
-c, --config-path TEXT Path to the metagit configuration file
--project TEXT
--repo TEXT
--json
-h, --help Show this message and exit.
config#
Configuration subcommands
Usage:
metagit config [OPTIONS] [COMMAND] [ARGS]...
Options:
-c, --config-path TEXT Path to the metagit configuration file
-h, --help Show this message and exit.
create#
Create metagit config files
Usage:
metagit config create [OPTIONS]
Options:
--output-path TEXT Path to the metagit configuration file
--name TEXT Project name
--description TEXT Project description
--url TEXT Project URL
--kind TEXT Project kind
-h, --help Show this message and exit.
example#
Generate a non-production YAML exemplar with optional field descriptions.
Merges src/metagit/data/config-example-overrides.yml when present.
Usage:
metagit config example [OPTIONS]
Options:
--output TEXT Write exemplar YAML to this path (default:
stdout)
--include-workspace / --no-include-workspace
Include the workspace block in the generated
exemplar
--comment-style [line|none] Emit Field descriptions as YAML comments
(line) or plain YAML only
-h, --help Show this message and exit.
graph#
Export workspace graph data for GitNexus / Cypher ingest.
Usage:
metagit config graph [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
export#
Export manual graph.relationships as GitNexus-ingestible Cypher.
Emits MERGE/CREATE statements for MetagitEntity / MetagitLink overlay tables and matching gitnexus_cypher MCP tool_calls. Run schema statements once per target index.
Usage:
metagit config graph export [OPTIONS]
Options:
-c, --config-path TEXT Path to the metagit configuration file
(overrides the config group's leaf path)
--workspace-root TEXT Workspace root (default: appconfig
workspace.path resolved against the manifest
directory)
--gitnexus-repo TEXT Target GitNexus repo name for tool_calls
(default: manifest name)
--include-structure / --no-include-structure
Include project/repo nodes and contains
edges
--include-documentation / --no-include-documentation
Include documentation nodes and documents
edges
--manual-only Only export graph.relationships (still
ensures endpoint nodes)
--with-schema / --no-with-schema
Emit CREATE NODE/REL TABLE statements first
--format [cypher|json|tool-calls]
Output: full JSON bundle, tool-calls array,
or raw Cypher lines [default: json]
--output TEXT Write output to file
-h, --help Show this message and exit.
suggest#
Suggest graph.relationships entries from inferred cross-project dependencies.
Returns candidates, diff against existing manual edges, and config patch operations. Use --apply to persist selected candidates (all by default, or --candidate-id).
Usage:
metagit config graph suggest [OPTIONS]
Options:
-c, --config-path TEXT Path to the metagit configuration file
(overrides the config group's leaf path)
--workspace-root TEXT Workspace root (default: appconfig
workspace.path resolved against the manifest
directory)
--dependency-type [imports|shared_config|url_match|declared|ref]
Inferred edge collectors to consider
(repeatable). Default: imports,
shared_config, url_match
--depth INTEGER Project-hop depth when scanning dependencies
[default: 3]
--min-confidence [high|medium|all]
Minimum confidence for candidates (high |
medium | all) [default: medium]
--include-declared Also consider declared/ref edges (usually
low confidence)
--candidate-id TEXT Apply only these candidate ids (repeatable)
--apply Patch graph.relationships on disk (default:
suggest only)
--dry-run With --apply, build operations without
saving
--json Print JSON
--verbose Log a detailed summary (roots, candidate
counts, prune stats) even with --json
--output TEXT Write JSON result or operations file
-h, --help Show this message and exit.
info#
Display information about the local project configuration.
Usage:
metagit config info [OPTIONS]
Options:
-h, --help Show this message and exit.
patch#
Apply schema operations to .metagit.yml (enable/disable/set/append/remove).
Same operation model as the web Config Studio PATCH API. Example operations file:
{"operations": [{"op": "set", "path": "name", "value": "my-workspace"}]}
Usage:
metagit config patch [OPTIONS]
Options:
--file FILE JSON file with operations array or
{operations, save}
--op [enable|disable|set|append|remove]
Single operation kind (use with --path)
--path TEXT Field path for a single operation
--value TEXT Value for set (JSON or scalar)
--save Write changes to disk when validation passes
--no-format Skip schema-ordered YAML formatting when
saving
--tree Include updated schema tree in JSON output
--json Print JSON for agents
-h, --help Show this message and exit.
preview#
Preview .metagit.yml after applying draft operations (no save).
Usage:
metagit config preview [OPTIONS]
Options:
--style [normalized|minimal|disk]
YAML preview style [default: normalized]
--file FILE JSON file with operations array or
{operations, save}
--op [enable|disable|set|append|remove]
Single operation kind (use with --path)
--path TEXT Field path for a single operation
--value TEXT Value for set (JSON or scalar)
--output TEXT Write preview YAML to this path instead of
stdout
--json Print JSON for agents
-h, --help Show this message and exit.
providers#
Manage git provider plugin configuration.
Usage:
metagit config providers [OPTIONS]
Options:
--show Show current provider configuration.
--enable-github Enable GitHub provider.
--disable-github Disable GitHub provider.
--enable-gitlab Enable GitLab provider.
--disable-gitlab Disable GitLab provider.
--github-token TEXT Set GitHub API token.
--gitlab-token TEXT Set GitLab API token.
--github-url TEXT Set GitHub API base URL (for GitHub Enterprise).
--gitlab-url TEXT Set GitLab API base URL (for self-hosted GitLab).
--config-path TEXT Path to configuration file (default:
~/.config/metagit/config.yml).
-h, --help Show this message and exit.
schema#
Generate a JSON schema for the MetagitConfig class and write it to a file.
Usage:
metagit config schema [OPTIONS]
Options:
--output-path TEXT Path to output the JSON schema file
-h, --help Show this message and exit.
set#
Set a specific configuration value.
Usage:
metagit config set [OPTIONS] KEY VALUE
Options:
-h, --help Show this message and exit.
show#
Show metagit configuration (source file by default).
Usage:
metagit config show [OPTIONS]
Options:
--normalized Re-serialize from the loaded model (readable YAML, not the
file on disk)
--json Print JSON for agents
--confirm-full Allow dumping a large umbrella manifest (over the repo
threshold)
-h, --help Show this message and exit.
tree#
Show schema-backed field tree for .metagit.yml (same model as web Config Studio).
Usage:
metagit config tree [OPTIONS]
Options:
--json Print JSON for agents
-h, --help Show this message and exit.
validate#
Validate metagit configuration
Usage:
metagit config validate [OPTIONS]
Options:
-c, --config-path TEXT Path to the configuration file
-h, --help Show this message and exit.
context#
Workspace context packs (tiered map and repo cards).
Usage:
metagit context [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
approval#
Human-in-the-loop approval queue.
Usage:
metagit context approval [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
approve#
Approve a pending request.
Usage:
metagit context approval approve [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
--note TEXT
-h, --help Show this message and exit.
deny#
Deny a pending request (note required).
Usage:
metagit context approval deny [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
--note TEXT [required]
-h, --help Show this message and exit.
list#
List approval requests (pending by default).
Usage:
metagit context approval list [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--status [pending|approved|denied|all]
[default: pending]
--json
-h, --help Show this message and exit.
request#
Create an approval request from JSON on stdin or flags.
Usage:
metagit context approval request [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--action TEXT
--requested-by TEXT
--idempotency-key TEXT
--payload TEXT JSON object string
-h, --help Show this message and exit.
compile#
Compile a budgeted context artifact for a project/repo (RFC-0009).
Usage:
metagit context compile [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition file
[default: .metagit.yml]
--project TEXT [required]
--repo TEXT [required]
--task-id TEXT Task node id (RFC-0008)
--graph-id TEXT Disambiguate task node graph
--objective-id TEXT Optional objective linkage
--tier INTEGER RANGE Context pack tier to compile [default: 1; 0<=x<=2]
--budget INTEGER RANGE Token budget (char/4 heuristic); falls back to task
context_budget [x>=1]
--profile TEXT Optional repomix profile name for suggested command
--component TEXT Optional component name or project/repo/component id
--depth INTEGER RANGE Component neighborhood depth (ignored without
--component) [default: 0; x>=0]
--json Print CompiledContext as JSON
-h, --help Show this message and exit.
events#
Emit workspace events since a cursor timestamp.
Usage:
metagit context events [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--since TEXT
--campaign TEXT Filter events to one campaign slug.
--objective TEXT Filter events to one objective id.
--json
-h, --help Show this message and exit.
handoff#
First-class multi-agent handoff queue operations.
Usage:
metagit context handoff [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
claim#
Claim a handoff for an assignee.
Usage:
metagit context handoff claim [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
--by TEXT [required]
--note TEXT
--ttl TEXT Claim lease duration (e.g. 30m, 2h, 3600).
-h, --help Show this message and exit.
complete#
Complete a handoff and append audit entry.
Usage:
metagit context handoff complete [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
--by TEXT [required]
--note TEXT
-h, --help Show this message and exit.
create#
Create a handoff with append-only audit history.
Usage:
metagit context handoff create [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--title TEXT [required]
--created-by TEXT
--payload TEXT JSON object string
-h, --help Show this message and exit.
heartbeat#
Renew an active handoff claim lease.
Usage:
metagit context handoff heartbeat [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
--by TEXT [required]
--ttl TEXT Renew lease duration (e.g. 30m, 2h).
-h, --help Show this message and exit.
list#
List handoffs, optionally filtered by status.
Usage:
metagit context handoff list [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--status [open|claimed|completed|cancelled]
--json
-h, --help Show this message and exit.
objective#
List, read, and update workspace objectives.
Usage:
metagit context objective [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
cancel#
Mark an objective cancelled.
Usage:
metagit context objective cancel [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
-h, --help Show this message and exit.
complete#
Mark an objective done.
Usage:
metagit context objective complete [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
-h, --help Show this message and exit.
edit#
Edit one objective field and print the saved objective JSON.
Usage:
metagit context objective edit [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
--field [title|status|repos|acceptance|human_notes|agent_notes]
[required]
--value TEXT
--repo TEXT
-h, --help Show this message and exit.
export#
Export objectives as a portable JSON envelope.
Usage:
metagit context objective export [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--output TEXT Write JSON to file
-h, --help Show this message and exit.
get#
Print one objective by id.
Usage:
metagit context objective get [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT [required]
--json
-h, --help Show this message and exit.
import#
Import objectives from a portable JSON envelope.
Usage:
metagit context objective import [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--input TEXT Read JSON from file
-h, --help Show this message and exit.
list#
List objectives persisted under .metagit/sessions/objectives.json.
Usage:
metagit context objective list [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--json
-h, --help Show this message and exit.
set#
Upsert an objective from JSON on stdin or from flags (--id and --title).
Usage:
metagit context objective set [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT
--title TEXT
--status [pending|in_progress|done|cancelled]
--repo TEXT
--human-notes TEXT
--left-off TEXT
--next TEXT
--blockers TEXT
--notes-file TEXT
-h, --help Show this message and exit.
pack#
Emit a tiered context pack (workspace map ± repo cards ± digest).
Usage:
metagit context pack [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition
file [default: .metagit.yml]
--tier INTEGER RANGE 0 = workspace map only; 1 = map + repo cards;
2 = tier 1 + session digest then touch
session boundary [0<=x<=2; required]
--project TEXT Limit cards and map rows (tier 0+)
--repo TEXT Limit cards and map rows (tier 0+)
--json Print ContextPackResult as JSON
--max-tokens INTEGER RANGE Optional token budget for context pack with
greedy drops [x>=1]
--max-cards INTEGER RANGE [default: 50; x>=1]
--max-map-repos INTEGER RANGE Max workspace map repo rows (tier 0+)
[default: 80; x>=1]
-h, --help Show this message and exit.
pause#
Upsert an in-progress objective from quick note-capture flags.
Usage:
metagit context pause [OPTIONS]
Options:
-c, --definition TEXT [default: .metagit.yml]
--id TEXT
--title TEXT
--repo TEXT
--human-notes TEXT
--left-off TEXT
--next TEXT
--blockers TEXT
--notes-file TEXT
-h, --help Show this message and exit.
repo-card#
Emit a single tier-1 repo card.
Usage:
metagit context repo-card [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition file
[default: .metagit.yml]
--project TEXT [required]
--repo TEXT [required]
--json Print RepoCardResult as JSON
-h, --help Show this message and exit.
repomix#
Run repomix with a bundled context profile for one managed repo.
Usage:
metagit context repomix [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition file
[default: .metagit.yml]
--profile TEXT [required]
--project TEXT [required]
--repo TEXT [required]
--output TEXT Write repomix output to this path instead of stdout
-h, --help Show this message and exit.
resume#
Select the best objective to resume, optionally filtered by substring.
Usage:
metagit context resume [OPTIONS] [FILTER_TEXT]
Options:
-c, --definition TEXT [default: .metagit.yml]
--format [concise|detailed] [default: concise]
--json
-h, --help Show this message and exit.
session#
Session lifecycle and bootstrap commands.
Usage:
metagit context session [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
begin#
Start a deterministic session envelope in one command.
Usage:
metagit context session begin [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition
file [default: .metagit.yml]
--project TEXT Optional project focus override
--repo TEXT Optional repo focus override
--max-tokens INTEGER RANGE Optional token budget for the embedded context
pack [x>=1]
--json
-h, --help Show this message and exit.
switch#
Switch project context and emit shell-evalable bootstrap exports.
Usage:
metagit context switch [OPTIONS] PROJECT [REPO]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml
definition file [default: .metagit.yml]
--tier INTEGER RANGE Context pack tier when packing (0=map,
1=cards, 2=digest) [default: 2; 0<=x<=2]
--no-pack Skip context pack
--no-prompt Skip prompt emission
--no-objective Skip objective upsert
--prompt-kind [context-switch|session-start]
Prompt template to emit [default: context-
switch]
--json Emit full envelope JSON
-h, --help Show this message and exit.
detect#
Detection subcommands
Usage:
metagit detect [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
project#
Perform project detection and analysis.
Usage:
metagit detect project [OPTIONS]
Options:
-p, --path TEXT Path to the git repository to analyze. [default: ./]
-o, --output TEXT Output format (yaml, json, summary). [default: yaml]
--output-file TEXT Write the full payload to this path and print a compact
status line (status=written path=... bytes=...
format=...). Prefer this over dumping yaml/json to
stdout in agent sessions.
-h, --help Show this message and exit.
repo#
Detect the codebase.
Usage:
metagit detect repo [OPTIONS]
Options:
-p, --path TEXT Path to the git repository to analyze. [default: ./]
-o, --output TEXT Output format (yaml, json, summary). [default: yaml]
--output-file TEXT Write the full payload to this path and print a compact
status line (status=written path=... bytes=...
format=...). Prefer this over dumping yaml/json to
stdout in agent sessions.
-h, --help Show this message and exit.
repo_map#
Create a directory map. Agents should avoid this command; it is large and rarely needed.
Usage:
metagit detect repo_map [OPTIONS]
Options:
-p, --path TEXT Path to the git repository to analyze. [default: ./]
-o, --output TEXT Output format (yaml, json, summary). [default: yaml]
--output-file TEXT Write the full payload to this path and print a compact
status line (status=written path=... bytes=...
format=...). Prefer this over dumping yaml/json to
stdout in agent sessions.
-h, --help Show this message and exit.
repository#
Comprehensive repository analysis and MetagitConfig generation using DetectionManager.
Usage:
metagit detect repository [OPTIONS]
Options:
-p, --path TEXT Path to local repository to analyze.
--url TEXT URL of remote git repository to clone and
analyze.
-o, --output [summary|yaml|json|record|metagit|metagitconfig|all]
Output format. Defaults to 'summary'
[default: summary]
--output-file TEXT Write the full payload to this path and
print a compact status line (status=written
path=... bytes=... format=...). Prefer this
over dumping yaml/json to stdout in agent
sessions.
-s, --save Save the generated configuration to
.metagit.yml in the repository path.
--temp-dir TEXT Temporary directory for cloning remote
repositories.
--github-token TEXT GitHub API token for fetching repository
metrics (overrides AppConfig).
--gitlab-token TEXT GitLab API token for fetching repository
metrics (overrides AppConfig).
--github-url TEXT GitHub API base URL (for GitHub Enterprise,
overrides AppConfig).
--gitlab-url TEXT GitLab API base URL (for self-hosted GitLab,
overrides AppConfig).
--use-app-config Use AppConfig for provider configuration
(default: True).
--config-path TEXT Path to the MetagitConfig file to save.
-f, --force Overwrite an existing .metagit.yml (disabled
in agent mode)
-h, --help Show this message and exit.
fmt#
Format .metagit.yml and/or metagit.config.yaml with schema field order and clean YAML.
By default, optional fields equal to schema defaults are omitted (including empty
lists and dicts). Use --include-defaults to retain them.
Re-serializes through the Pydantic models so keys like name appear first in
project/repo list entries, preserves YAML comments, injects a yaml-language-server
schema directive, and uses two-space indentation.
Usage:
metagit fmt [OPTIONS]
Options:
-t, --target [metagit|appconfig|all]
Which configuration file(s) to format
[default: all]
--metagit-path TEXT Path to .metagit.yml when formatting the
manifest [default: .metagit.yml]
--appconfig-path TEXT Path to metagit.config.yaml (default: global
--config from CLI context)
--include-defaults Include optional fields set to schema
defaults (empty lists/dicts, false, etc.)
--check Exit 1 when a file would change (no writes)
--stdout Print formatted YAML to stdout instead of
writing files
-h, --help Show this message and exit.
fmt#
Format .metagit.yml and/or metagit.config.yaml with schema field order and clean YAML.
By default, optional fields equal to schema defaults are omitted (including empty
lists and dicts). Use --include-defaults to retain them.
Re-serializes through the Pydantic models so keys like name appear first in
project/repo list entries, preserves YAML comments, injects a yaml-language-server
schema directive, and uses two-space indentation.
Usage:
metagit fmt [OPTIONS]
Options:
-t, --target [metagit|appconfig|all]
Which configuration file(s) to format
[default: all]
--metagit-path TEXT Path to .metagit.yml when formatting the
manifest [default: .metagit.yml]
--appconfig-path TEXT Path to metagit.config.yaml (default: global
--config from CLI context)
--include-defaults Include optional fields set to schema
defaults (empty lists/dicts, false, etc.)
--check Exit 1 when a file would change (no writes)
--stdout Print formatted YAML to stdout instead of
writing files
-h, --help Show this message and exit.
gitnexus#
GitNexus workspace integration (groups, cross-index analysis).
Usage:
metagit gitnexus [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
group#
Manage GitNexus repository groups.
Usage:
metagit gitnexus group [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
sync#
Sync workspace.projects repos into a GitNexus group and run contract linking.
Creates the group when missing (unless --no-create). Each indexed checkout must
be registered in ~/.gitnexus/registry.json (run gitnexus analyze first). Group
paths use <project>/<repo>; registry names come from the global registry.
Usage:
metagit gitnexus group sync [OPTIONS]
Options:
--workspace-root TEXT Workspace sync root (default: appconfig
workspace.path resolved against the manifest
directory)
--group-name TEXT GitNexus group name (default: slug of manifest name)
--no-create Fail when the group does not exist instead of
creating it
--prune Remove group members no longer present in
workspace.projects
--no-contract-sync Update group membership only; skip gitnexus group
sync
--allow-stale Pass --allow-stale
--skip-embeddings Pass --skip-embeddings to contract sync
--exact-only Pass --exact-only to contract sync
--verbose Verbose contract sync
--json Print JSON result
-h, --help Show this message and exit.
graph#
Inspect workspace and organization repository relationships.
Usage:
metagit graph [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
neighbors#
Show graph neighbors, including repositories that are only indexed.
Usage:
metagit graph neighbors [OPTIONS] REPOSITORY
Options:
-c, --config-path TEXT Path to .metagit.yml
--json Print a JSON envelope.
-h, --help Show this message and exit.
info#
Display the current configuration.
Usage:
metagit info [OPTIONS]
Options:
-h, --help Show this message and exit.
init#
Initialize metagit with a validated manifest and optional companion files.
TARGET is the folder to write into (default: current directory). Use --target to pass a path when you prefer a flag over the positional argument.
Usage:
metagit init [OPTIONS] [TARGET]
Options:
--target DIRECTORY Target folder to initialize (overrides
positional TARGET)
--create Create the target directory if it does not
exist
-t, --template TEXT Bundled init template id (see --list-
templates)
--list-templates List bundled init templates and exit
--answers-file FILE YAML/JSON file with template answers
(copier-style)
--no-prompt Do not prompt; use defaults and answers file
only
-k, --kind [monorepo|umbrella|application|gitops|infrastructure|service|library|website|other|docker_image|repository|cli]
Project kind (used when no bundled template
exists for this kind)
-n, --name TEXT Override manifest name
-d, --description TEXT Override manifest description
-u, --url TEXT Override manifest git URL
--minimal Skip bundled templates; write minimal
schema-backed manifest for --kind
-f, --force Overwrite existing .metagit.yml
-s, --skip-gitignore Skip updating .gitignore
--dry-run Validate and render without writing files
-h, --help Show this message and exit.
lane#
Evaluate lane-tier promotion state from run evidence.
Usage:
metagit lane [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
eval#
Recompute tier and promotion state from run outcomes.
Usage:
metagit lane eval [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition file
[default: .metagit.yml]
--id TEXT
--dry-run
--json
-h, --help Show this message and exit.
lease#
Manage ACL branch leases (not handoff claim leases).
Usage:
metagit lease [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
acquire#
Acquire a branch lease for an agent.
Usage:
metagit lease acquire [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT project/repo, or . / self for the definition repo
[required]
--agent-id TEXT [required]
--task-id TEXT [required]
--branch TEXT Allocated agent/* branch name
--branch-id TEXT
--ttl TEXT [default: 30m]
--allocate Allocate branch if missing
--description TEXT
--integration-branch TEXT
--base TEXT
--json
-h, --help Show this message and exit.
list#
List ACL branch leases and advisory repo presence.
Usage:
metagit lease list [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT
--status TEXT
--agent-id TEXT
--json
-h, --help Show this message and exit.
release#
Release an ACL branch lease.
Usage:
metagit lease release [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--lease-id TEXT [required]
--agent-id TEXT [required]
--force
--release-branch Also mark branch allocation released
--json
-h, --help Show this message and exit.
renew#
Renew an ACL branch lease.
Usage:
metagit lease renew [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--lease-id TEXT [required]
--agent-id TEXT [required]
--ttl TEXT [default: 30m]
--force
--json
-h, --help Show this message and exit.
mcp#
Metagit MCP server commands.
Usage:
metagit mcp [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
install#
Install metagit MCP server entry into supported agent configs.
Usage:
metagit mcp install [OPTIONS]
Options:
--scope [project|user] Install to the git repository root (project)
or user-global location. [default: user]
--target [opencode|hermes|openclaw|claude_code|cursor|github_copilot|windsurf|codex]
Explicit target to install (repeatable). If
omitted, auto-detect targets.
--disable-target [opencode|hermes|openclaw|claude_code|cursor|github_copilot|windsurf|codex]
Disable one or more auto-detected targets.
--server-name TEXT MCP server key to write in target config
files. [default: metagit]
-h, --help Show this message and exit.
serve#
Start MCP runtime over stdio.
Usage:
metagit mcp serve [OPTIONS]
Options:
--root TEXT Optional workspace root override.
--status-once Print one-shot status and exit (for diagnostics/tests).
-h, --help Show this message and exit.
merge#
Manage local merge orchestration records.
Usage:
metagit merge [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
enqueue#
Enqueue an agent branch merge into an integration branch.
Usage:
metagit merge enqueue [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT project/repo, or . / self for the definition repo
[required]
--branch TEXT [required]
--into TEXT [required]
--node-id TEXT
--agent-id TEXT
--repo-path TEXT
--json
-h, --help Show this message and exit.
integrate#
Attempt the queued merge.
Usage:
metagit merge integrate [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--merge-id TEXT [required]
--repo-path TEXT
--json
-h, --help Show this message and exit.
promote#
Promote a validated integration branch into another branch.
Usage:
metagit merge promote [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--merge-id TEXT [required]
--into TEXT [required]
--repo-path TEXT
--json
-h, --help Show this message and exit.
retry#
Retry a failed, conflicting, or validation-failed merge.
Usage:
metagit merge retry [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--merge-id TEXT [required]
--repo-path TEXT
--json
-h, --help Show this message and exit.
rollup#
Merge branches into one integration branch. Does not push or open a pull request.
Usage:
metagit merge rollup [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT project/repo, or . / self for the definition repo
[required]
--into TEXT Integration branch to create or extend [required]
--base TEXT Start point used when --into does not exist [required]
--branches TEXT Branch name, glob, or comma-separated list. Repeat to add
more. [required]
--repo-path TEXT
--json
-h, --help Show this message and exit.
status#
List merge requests.
Usage:
metagit merge status [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT
--json
-h, --help Show this message and exit.
nav#
Pick a project, then a repo, and open it in the configured editor.
Usage:
metagit nav [OPTIONS]
Options:
-c, --config TEXT Path to the metagit definition file [default:
.metagit.yml]
-p, --project TEXT Project within workspace (skips project picker)
--repo TEXT Repository name (skips repo picker)
--all Single FuzzyFinder over all managed project/repo targets
(ignores --project/--repo)
--unmanaged With --all, also list unmanaged sync-folder directories
--print-path Print the selected absolute path to stdout instead of
opening an editor
-h, --help Show this message and exit.
nav#
Pick a project, then a repo, and open it in the configured editor.
Usage:
metagit nav [OPTIONS]
Options:
-c, --config TEXT Path to the metagit definition file [default:
.metagit.yml]
-p, --project TEXT Project within workspace (skips project picker)
--repo TEXT Repository name (skips repo picker)
--all Single FuzzyFinder over all managed project/repo targets
(ignores --project/--repo)
--unmanaged With --all, also list unmanaged sync-folder directories
--print-path Print the selected absolute path to stdout instead of
opening an editor
-h, --help Show this message and exit.
org#
Index and search GitHub organizations without cloning every repository.
Usage:
metagit org [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
index#
Build or refresh a disposable organization index.
Usage:
metagit org index [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
github#
Index GitHub organization repositories into ~/.metagit/indexes/github/.
Usage:
metagit org index github [OPTIONS] ORGANIZATION
Options:
--refresh Re-fingerprint repositories whose GitHub pushed_at changed.
--full Fetch languages, trees, and extra GitHub metadata for every
repository.
--json Print a JSON envelope.
-h, --help Show this message and exit.
search#
Search indexed organization repositories. No local checkouts required.
Usage:
metagit org search [OPTIONS] [QUERY]
Options:
--organization, --org TEXT Limit search to one indexed GitHub organization.
--language TEXT Primary language filter (csharp, python, …).
--topic TEXT GitHub topic filter.
--has TEXT Fingerprint path, filename, or detector tag
(Dockerfile, terraform).
--stale-days INTEGER Only repositories not pushed within N days.
--limit INTEGER [default: 50]
--json Print a JSON envelope.
-h, --help Show this message and exit.
policy#
Evaluate declarative mutation policy.
Usage:
metagit policy [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
eval#
Evaluate whether an action class is allowed (report-only).
Usage:
metagit policy eval [OPTIONS]
Options:
--action [sync|merge_integrate|claim_declare|claim_release|catalog_edit|remote_state_write|acl_bind|aos_recover|run_open]
[required]
--json
-h, --help Show this message and exit.
project#
Project subcommands
Usage:
metagit project [OPTIONS] [COMMAND] [ARGS]...
Options:
-c, --config TEXT Path to the metagit definition file
-p, --project TEXT Project within workspace to operate on
-h, --help Show this message and exit.
add#
Add a workspace project to the manifest.
Usage:
metagit project add [OPTIONS] NAME
Options:
--description TEXT
--agent-instructions TEXT
--ensure Succeed without changes when the project already
exists with matching fields
--json Print JSON for agents
-h, --help Show this message and exit.
derived#
Create and maintain derived surgical workspace projects.
Usage:
metagit project derived [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
create#
Create a derived project from frozen project/repo or project/repo/component selections.
Usage:
metagit project derived create [OPTIONS]
Options:
-n, --name TEXT Name for the new derived project [required]
--from TEXT Source selection as project/repo or
project/repo/component (repeatable) [required]
--description TEXT Optional project description
--agent-instructions TEXT Optional agent instructions for the derived
project
--include-dependencies Also copy outbound depends_on neighbors of
component selections
--no-dedupe Do not enable per-project dedupe (fails if
identities already exist)
--json Print JSON for agents
-h, --help Show this message and exit.
exclude#
Remove one repo from a derived project's frozen membership.
Usage:
metagit project derived exclude [OPTIONS]
Options:
-p, --project TEXT Derived project name (defaults to active -p on project
group)
-r, --repo TEXT Derived repo name to remove [required]
--force Allow exclude on protected repos
--json Print JSON for agents
-h, --help Show this message and exit.
include#
Add one source repo to a derived project's frozen membership.
Usage:
metagit project derived include [OPTIONS]
Options:
-p, --project TEXT Derived project name (defaults to active -p on project
group)
--from TEXT Source selection as project/repo or
project/repo/component [required]
--force Allow include on protected projects
--json Print JSON for agents
-h, --help Show this message and exit.
refresh#
Re-pull identity fields from source without changing membership.
Usage:
metagit project derived refresh [OPTIONS]
Options:
-p, --project TEXT Derived project name (defaults to active -p on project
group)
-r, --repo TEXT Limit refresh to these derived repo names (repeatable)
--force Allow refresh on protected projects
--json Print JSON for agents
-h, --help Show this message and exit.
list#
List workspace projects (catalog), or one project with -p/--detail.
Usage:
metagit project list [OPTIONS]
Options:
--all Deprecated alias: catalog listing is now the default without
-p/--project
--detail Dump the active/explicit project as YAML (or JSON with --json)
--json Print JSON for agents
-h, --help Show this message and exit.
remove#
Remove a workspace project from the manifest.
Usage:
metagit project remove [OPTIONS] NAME
Options:
--json Print JSON for agents
-h, --help Show this message and exit.
rename#
Rename a workspace project (alias for workspace project rename).
Usage:
metagit project rename [OPTIONS] FROM_NAME TO_NAME
Options:
--dry-run
--manifest-only
--force
--json Print JSON for agents
-h, --help Show this message and exit.
repo#
Repository subcommands
Usage:
metagit project repo [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
add#
Add a repository to the current project
Usage:
metagit project repo add [OPTIONS]
Options:
-n, --name TEXT Repository name
-d, --description TEXT Repository description
--ref TEXT Reference in the current project for the target
project
--path TEXT Local project path
--url TEXT Remote git URL (ssh or https)
--sync / --no-sync Sync setting
--language TEXT Programming language
--language-version TEXT Language version
--package-manager TEXT Package manager
--frameworks TEXT Frameworks used (can be specified multiple times)
--prompt Use interactive prompts instead of command line
parameters
--ensure Succeed without changes when the repo already
exists with matching url/path
--json Print JSON for agents
-h, --help Show this message and exit.
ci#
Show, detect, and set repository CI topology bindings.
Usage:
metagit project repo ci [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
detect#
Detect CI topology from remote URL and on-disk CI config files.
Usage:
metagit project repo ci detect [OPTIONS]
Options:
--repo TEXT Repository name within the active project [required]
--apply / --no-apply Write detected ci into .metagit.yml [default: no-
apply]
--force Re-detect even when status is declared/overridden
--json Emit JSON
-h, --help Show this message and exit.
set#
Declare or override durable CI topology for a managed repository.
Usage:
metagit project repo ci set [OPTIONS]
Options:
--repo TEXT Repository name within the active project
[required]
--provider [github|gitlab|azure_devops|other|none|unknown]
[required]
--config-path TEXT Repo-relative CI file (repeatable)
--organization TEXT Azure DevOps organization
--ado-project TEXT Azure DevOps project
--repository TEXT Azure DevOps repository name
--definition-id TEXT ADO definition id (repeatable)
--owner TEXT GitHub owner
--name TEXT GitHub repo name
--project-path TEXT GitLab project path
--host TEXT CI host override
--status [declared|overridden] [default: declared]
--json Emit JSON
-h, --help Show this message and exit.
show#
Show durable CI topology for a managed repository.
Usage:
metagit project repo ci show [OPTIONS]
Options:
--repo TEXT Repository name within the active project [required]
--json Emit JSON
-h, --help Show this message and exit.
list#
List repositories for the current workspace project.
Usage:
metagit project repo list [OPTIONS]
Options:
--json Print JSON for agents
-h, --help Show this message and exit.
move#
Move a repository to another workspace project.
Usage:
metagit project repo move [OPTIONS]
Options:
-n, --name TEXT Repository name [required]
--to-project TEXT Target workspace project [required]
--dry-run
--manifest-only
--force
--json Print JSON for agents
-h, --help Show this message and exit.
promote#
Promote a path-based repo entry to a git-managed clone under the sync folder.
Removes the existing symlink mount (if any), clears path in the manifest,
sets url, and runs project sync to clone into the managed workspace.
Usage:
metagit project repo promote [OPTIONS]
Options:
-n, --name TEXT Repository name to promote [required]
--url TEXT Remote git URL (default: manifest url or git origin on
source path)
--remote TEXT Remote name when discovering URL from the source git repo
[default: origin]
--dry-run Show planned changes without updating manifest or cloning
--force Promote protected repos
--json Print JSON for agents
-h, --help Show this message and exit.
prune#
Walk the project sync folder and offer to remove directories not in .metagit.yml.
Only considers immediate children of the project directory (same layout as sync).
Usage:
metagit project repo prune [OPTIONS]
Options:
--dry-run List unmanaged directories only; do not prompt or delete.
--include-hidden Include dot-directories (overrides
workspace.ui_ignore_hidden).
--force Remove all listed unmanaged paths without prompting (no
effect with --dry-run).
-h, --help Show this message and exit.
remove#
Remove a repository from the manifest (does not delete files).
Usage:
metagit project repo remove [OPTIONS]
Options:
-n, --name TEXT Repository name [required]
--json Print JSON for agents
-h, --help Show this message and exit.
rename#
Rename a repository in the current project.
Usage:
metagit project repo rename [OPTIONS] TO_NAME
Options:
-n, --name TEXT Current repository name [required]
--dry-run
--manifest-only
--force
--json Print JSON for agents
-h, --help Show this message and exit.
select#
Select project repo to work on
Usage:
metagit project repo select [OPTIONS]
Options:
--repo TEXT Open this repository in the default editor without the picker
TUI
-h, --help Show this message and exit.
select#
Shortcut: Uses 'project repo select' to select workspace project repo to work on
Usage:
metagit project select [OPTIONS]
Options:
--repo TEXT Open this repository in the default editor without the picker
TUI
-h, --help Show this message and exit.
source#
Source-backed project sync operations.
Usage:
metagit project source [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
sync#
Discover and sync repositories from provider sources.
Usage:
metagit project source sync [OPTIONS]
Options:
--provider [github|gitlab|azure_devops]
Source provider (not used with --from-
manifest)
--org TEXT GitHub organization to discover repositories
from
--user TEXT GitHub user to discover repositories from
--group TEXT GitLab group path to discover repositories
from
--organization TEXT Azure DevOps organization
--ado-project TEXT Azure DevOps project filter
--mode [discover|additive|reconcile]
Sync mode [default: discover]
--recursive / --no-recursive Recursive traversal when supported by
provider [default: recursive]
--include-archived / --no-include-archived
Include archived repositories [default: no-
include-archived]
--include-forks / --no-include-forks
Include forks [default: no-include-forks]
--path-prefix TEXT Optional namespace/repo prefix filter
--include-pattern TEXT fnmatch allowlist on provider full_name
(repeatable)
--ignore TEXT fnmatch denylist on provider full_name
(repeatable)
--name-strategy [short|namespaced]
Manifest repo naming strategy [default:
namespaced]
--ensure Skip metadata updates when repo URL already
exists
--refresh-metadata With --ensure, still refresh description and
tags
--no-enrich-topics Do not merge provider topics into repo tags
--apply / --no-apply Apply computed changes to .metagit.yml
[default: no-apply]
--yes Confirm destructive reconcile removals
--sync / --no-sync Run project git sync after a successful
manifest apply [default: no-sync]
--json Print JSON result for agents
--from-manifest Sync using workspace.projects[].sources[]
definitions
--source-id TEXT Limit manifest sync to one source id
--write-source Persist current CLI flags as a sources[]
entry (requires --source-id)
--force Apply reconcile removals without approval
(manifest mode)
-h, --help Show this message and exit.
sync#
Sync project within workspace
Usage:
metagit project sync [OPTIONS]
Options:
--hydrate After sync, replace symlink mounts with full directory
copies
--refresh-sources Apply workspace.projects[].sources[] before git sync
-h, --help Show this message and exit.
prompt#
Emit metagit prompts for workspace, project, and repo scopes.
Usage:
metagit prompt [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
list#
List available prompt kinds and valid scopes.
Usage:
metagit prompt list [OPTIONS]
Options:
--json Print JSON for agents
-h, --help Show this message and exit.
project#
Emit a prompt scoped to one workspace project.
Usage:
metagit prompt project [OPTIONS]
Options:
-p, --project TEXT Workspace project name [required]
-c, --definition TEXT [default: .metagit.yml]
-k, --kind [catalog-edit|context-pack|health-preflight|instructions|layout-change|subagent-handoff|sync-safe]
[default: instructions]
--no-instructions
--json
--text-only
-h, --help Show this message and exit.
repo#
Emit a prompt scoped to one repository entry.
Usage:
metagit prompt repo [OPTIONS]
Options:
-p, --project TEXT Workspace project name [required]
-n, --repo TEXT Repository name [required]
-c, --definition TEXT [default: .metagit.yml]
-k, --kind [context-pack|instructions|layout-change|repo-enrich|subagent-handoff|sync-safe]
[default: instructions]
--no-instructions
--json
--text-only
-h, --help Show this message and exit.
workspace#
Emit a prompt for the whole workspace manifest.
Usage:
metagit prompt workspace [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml
definition file [default: .metagit.yml]
-k, --kind [catalog-edit|context-pack|context-switch|graph-discover|graph-maintain|health-preflight|instructions|large-workspace|layout-change|session-start|sync-safe]
Prompt kind to emit [default: instructions]
--no-instructions Omit composed manifest instructions from
operational prompts
--json Print JSON for agents
--text-only Print prompt text only (no JSON wrapper)
-h, --help Show this message and exit.
record#
Record management subcommands
Usage:
metagit record [OPTIONS] [COMMAND] [ARGS]...
Options:
--storage-type [local|opensearch]
Storage backend type for records
--storage-path TEXT Path for local storage (used when storage-
type is 'local')
--opensearch-hosts TEXT OpenSearch hosts (comma-separated, used when
storage-type is 'opensearch')
--opensearch-index TEXT OpenSearch index name (used when storage-
type is 'opensearch')
--opensearch-username TEXT OpenSearch username (used when storage-type
is 'opensearch')
--opensearch-password TEXT OpenSearch password (used when storage-type
is 'opensearch')
--opensearch-use-ssl Use SSL for OpenSearch connection
-h, --help Show this message and exit.
create#
Create a record from metagit configuration
Usage:
metagit record create [OPTIONS]
Options:
--config-path TEXT Path to the metagit configuration file
--detection-source TEXT Source of the detection
--detection-version TEXT Version of the detection system
--output-file TEXT Save record to file (optional)
-h, --help Show this message and exit.
delete#
Delete a record
Usage:
metagit record delete [OPTIONS] RECORD_ID
Options:
--force Force deletion without confirmation
-h, --help Show this message and exit.
export#
Export a record to file
Usage:
metagit record export [OPTIONS] RECORD_ID OUTPUT_FILE
Options:
--format [yaml|json] Export format
-h, --help Show this message and exit.
import#
Import a record from file
Usage:
metagit record import [OPTIONS] INPUT_FILE
Options:
--detection-source TEXT Override detection source
--detection-version TEXT Override detection version
-h, --help Show this message and exit.
search#
Search records
Usage:
metagit record search [OPTIONS] QUERY
Options:
--page INTEGER Page number for pagination
--size INTEGER Number of records per page
--format [yaml|json|table] Output format
-h, --help Show this message and exit.
show#
Show record(s)
Usage:
metagit record show [OPTIONS] [RECORD_ID]
Options:
--format [yaml|json] Output format
-h, --help Show this message and exit.
stats#
Show record storage statistics
Usage:
metagit record stats [OPTIONS]
Options:
-h, --help Show this message and exit.
update#
Update an existing record
Usage:
metagit record update [OPTIONS] RECORD_ID
Options:
--config-path TEXT Path to the updated metagit configuration file
--detection-source TEXT Updated detection source
--detection-version TEXT Updated detection version
-h, --help Show this message and exit.
repo#
Repository operations that are not bound to an already materialized checkout.
Usage:
metagit repo [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
materialize#
Clone an indexed repository and enroll it as a local metagit repository.
Usage:
metagit repo materialize [OPTIONS] REPOSITORY
Options:
-c, --config-path TEXT Path to .metagit.yml
--project TEXT Workspace project to enroll the repository under.
--dry-run Resolve and plan without cloning or writing the
manifest.
--no-clone Enroll in the manifest without cloning.
--json Print a JSON envelope.
-h, --help Show this message and exit.
route#
Query and inspect routing request classes.
Usage:
metagit route [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
list#
List routing classes with optional tier and readiness filters.
Usage:
metagit route list [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml
definition file [default: .metagit.yml]
--tier [deterministic|skilled|novel]
--ready Only show classes waiting on executor
promotion
--json
-h, --help Show this message and exit.
query#
Resolve a natural-language ask to ranked request classes.
Usage:
metagit route query [OPTIONS] ASK
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition file
[default: .metagit.yml]
--limit INTEGER RANGE [default: 5; x>=1]
--json
-h, --help Show this message and exit.
show#
Show one class plus run history.
Usage:
metagit route show [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition file
[default: .metagit.yml]
--id TEXT [required]
--json
-h, --help Show this message and exit.
run#
Open, close, and list routing run records.
Usage:
metagit run [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
close#
Close one open run with an outcome and optional evidence.
Usage:
metagit run close [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml
definition file [default: .metagit.yml]
--id TEXT [required]
--outcome [landed|bounced|noop|abandoned]
[required]
--mr-url TEXT
--gate TEXT
--evidence-file TEXT
--json
-h, --help Show this message and exit.
export#
Export run records as JSON (redacted by default).
Usage:
metagit run export [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml
definition file [default: .metagit.yml]
--class TEXT
--outcome [landed|bounced|noop|abandoned]
--open
--no-redact
--json
-h, --help Show this message and exit.
list#
List runs with optional filters.
Usage:
metagit run list [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml
definition file [default: .metagit.yml]
--class TEXT
--outcome [landed|bounced|noop|abandoned]
--open
--json
-h, --help Show this message and exit.
open#
Open a run for a request class.
Usage:
metagit run open [OPTIONS]
Options:
-c, --definition TEXT Path to the workspace .metagit.yml
definition file [default: .metagit.yml]
--class TEXT [required]
--actor TEXT [required]
--tier [deterministic|skilled|novel]
--lane TEXT
--objective TEXT
--session-id TEXT
--branch TEXT
--workdir TEXT
--doctrine-chars INTEGER RANGE [x>=0]
--json
-h, --help Show this message and exit.
replay#
Replay control-loop steps for a run (report-only).
Usage:
metagit run replay [OPTIONS] RUN_ID
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition file
[default: .metagit.yml]
--dry-run Reconstruct control-loop steps without mutations
(default)
--no-redact
--json
-h, --help Show this message and exit.
show#
Show one run record (redacted by default).
Usage:
metagit run show [OPTIONS] RUN_ID
Options:
-c, --definition TEXT Path to the workspace .metagit.yml definition file
[default: .metagit.yml]
--no-redact Skip secret redaction
--json
-h, --help Show this message and exit.
schedule#
Score ready tasks and emit schedule decisions (RFC-0012).
Usage:
metagit schedule [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
next#
Return the next schedule decision(s) for ready task nodes.
Usage:
metagit schedule next [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--graph-id TEXT
--limit INTEGER [default: 1]
--json
-h, --help Show this message and exit.
policy#
Show or update the local schedule policy.
Usage:
metagit schedule policy [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
set#
Update schedule policy weights and merge-pressure settings.
Usage:
metagit schedule policy set [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--priority FLOAT
--affinity FLOAT
--cost FLOAT
--fairness FLOAT
--merge-queue-threshold INTEGER
--merge-pressure-penalty FLOAT
--skip-on-merge-pressure / --no-skip-on-merge-pressure
--graph-id TEXT Optional graph override target
--json
-h, --help Show this message and exit.
show#
Show the workspace schedule policy.
Usage:
metagit schedule policy show [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--json
-h, --help Show this message and exit.
status#
Show scheduler policy, ready count, and recent decisions.
Usage:
metagit schedule status [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--recent INTEGER [default: 10]
--json
-h, --help Show this message and exit.
search#
Search managed repositories declared in .metagit.yml (alias: metagit find).
Usage:
metagit search [OPTIONS] QUERY
Options:
--definition TEXT Path to the Metagit workspace definition file
[default: .metagit.yml]
--project TEXT Limit to a single workspace project name
--exact Require exact repository name match
--synced-only Only include repositories that exist on disk as
git checkouts
--tag TEXT Filter by tag (repeatable), e.g. --tag
domain=terraform-module
--status TEXT Filter by repo status (repeatable), e.g.
--status synced
--sort [score|project|name] [default: score]
--limit INTEGER [default: 10]
--json Print matches as JSON
--path-only Resolve to a single local path (errors if
ambiguous or not found)
-h, --help Show this message and exit.
search#
Search managed repositories declared in .metagit.yml (alias: metagit find).
Usage:
metagit search [OPTIONS] QUERY
Options:
--definition TEXT Path to the Metagit workspace definition file
[default: .metagit.yml]
--project TEXT Limit to a single workspace project name
--exact Require exact repository name match
--synced-only Only include repositories that exist on disk as
git checkouts
--tag TEXT Filter by tag (repeatable), e.g. --tag
domain=terraform-module
--status TEXT Filter by repo status (repeatable), e.g.
--status synced
--sort [score|project|name] [default: score]
--limit INTEGER [default: 10]
--json Print matches as JSON
--path-only Resolve to a single local path (errors if
ambiguous or not found)
-h, --help Show this message and exit.
semantic#
Manage semantic concept ownership.
Usage:
metagit semantic [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
conflicts#
Show advisory concept conflict hints for active ACL claims.
Usage:
metagit semantic conflicts [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT [required]
--json
-h, --help Show this message and exit.
declare#
Declare semantic ownership for repository path patterns.
Usage:
metagit semantic declare [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--concept TEXT [required]
--repository TEXT [required]
--pattern TEXT [required]
--json
-h, --help Show this message and exit.
ingest#
Ingest deterministic semantic ownership hints.
Usage:
metagit semantic ingest [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--json
-h, --help Show this message and exit.
owners#
Resolve semantic concepts that own a repository path.
Usage:
metagit semantic owners [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--path TEXT [required]
--repository TEXT [required]
--json
-h, --help Show this message and exit.
query#
Query a semantic concept and its ownership declarations.
Usage:
metagit semantic query [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--concept TEXT [required]
--json
-h, --help Show this message and exit.
seed#
Seed the static semantic concept catalog for a repository.
Usage:
metagit semantic seed [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT [required]
--json
-h, --help Show this message and exit.
skills#
Bundled skill management commands.
Usage:
metagit skills [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
install#
Install bundled skills into supported agent targets.
Usage:
metagit skills install [OPTIONS]
Options:
--scope [project|user] Install to the git repository root (project)
or user-global location. [default: user]
--target [opencode|hermes|openclaw|claude_code|cursor|github_copilot|windsurf|codex]
Explicit target to install (repeatable). If
omitted, auto-detect targets.
--disable-target [opencode|hermes|openclaw|claude_code|cursor|github_copilot|windsurf|codex]
Disable one or more auto-detected targets.
--skill TEXT Install only this bundled skill
(repeatable). Omit to install all.
--dry-run Show what would be installed without writing
files.
-h, --help Show this message and exit.
list#
List bundled skills available for install.
Usage:
metagit skills list [OPTIONS]
Options:
-h, --help Show this message and exit.
show#
Show a bundled skill document.
Usage:
metagit skills show [OPTIONS] [SKILL_NAME]
Options:
-h, --help Show this message and exit.
surface#
Inventory on-disk and declared skills across workspace/project/repo scopes.
Usage:
metagit skills surface [OPTIONS]
Options:
-c, --config TEXT Path to the metagit definition file
-p, --project TEXT Limit inventory to one workspace project
-r, --repo TEXT Limit inventory to one repo
--json Print JSON for agents
-h, --help Show this message and exit.
task#
Manage task graphs and intent nodes (RFC-0008).
Usage:
metagit task [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
bind-acl#
Store ACL command hints on a node (does not run git/ACL).
Usage:
metagit task bind-acl [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--node-id TEXT [required]
--agent-id TEXT [required]
--graph-id TEXT
--branch TEXT
--lease-id TEXT
--worktree-id TEXT
--pattern TEXT Claim pattern hint
--json
-h, --help Show this message and exit.
block#
Mark a node blocked.
Usage:
metagit task block [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--node-id TEXT [required]
--reason TEXT [required]
--graph-id TEXT
--json
-h, --help Show this message and exit.
complete#
Mark a node completed and unlock dependents.
Usage:
metagit task complete [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--node-id TEXT [required]
--graph-id TEXT
--json
-h, --help Show this message and exit.
create#
Create an empty task graph with a root intent.
Usage:
metagit task create [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--title TEXT [required]
--goal TEXT [required]
--acceptance TEXT Acceptance criterion (repeatable)
--objective-id TEXT
--handoff-id TEXT
--project TEXT
--repo TEXT
--graph-id TEXT
--json
-h, --help Show this message and exit.
expand#
Expand a graph from an indented outline or JSON list.
Usage:
metagit task expand [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--graph-id TEXT [required]
--from-outline FILE Path to outline file; omit to read STDIN
--json
-h, --help Show this message and exit.
list#
List graphs or nodes.
Usage:
metagit task list [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--graph-id TEXT
--status TEXT Filter nodes by status
--json
-h, --help Show this message and exit.
ready#
List nodes whose dependencies are satisfied.
Usage:
metagit task ready [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--graph-id TEXT
--json
-h, --help Show this message and exit.
start#
Mark a node running (without scheduler).
Usage:
metagit task start [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--node-id TEXT [required]
--graph-id TEXT
--json
-h, --help Show this message and exit.
status#
Show one node.
Usage:
metagit task status [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--node-id TEXT [required]
--graph-id TEXT
--json
-h, --help Show this message and exit.
tui#
Launch the Metagit TUI hub.
Browse common CLI workflows, run commands, and configure metagit.config.yaml.
Usage:
metagit tui [OPTIONS]
Options:
-m, --manifest FILE Path to .metagit.yml (default: ./.metagit.yml when
present)
--wizard Open directly on the configuration wizard
-h, --help Show this message and exit.
version#
Show installed Metagit version or check for updates.
Usage:
metagit version [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
check#
Compare installed Metagit against the latest GitHub release and PyPI.
Usage:
metagit version check [OPTIONS]
Options:
--json Print structured JSON for agents
--no-notes Omit release notes body from the response
-h, --help Show this message and exit.
upgrade#
Upgrade Metagit when a newer release is published on PyPI.
Usage:
metagit version upgrade [OPTIONS]
Options:
--json Print structured JSON for agents
--apply Execute the upgrade (default is dry-run)
-h, --help Show this message and exit.
web#
Local web UI commands.
Usage:
metagit web [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
serve#
Serve the metagit web UI and workspace API on localhost.
Usage:
metagit web serve [OPTIONS]
Options:
--root TEXT Directory containing `.metagit.yml`. [default: .]
--appconfig TEXT App config path override.
--host TEXT [default: 127.0.0.1]
--port INTEGER [default: 8787]
--open / --no-open Open the UI in a browser.
--status-once Bind once, print ready line with resolved port, and
exit.
-h, --help Show this message and exit.
workspace#
Workspace subcommands
Usage:
metagit workspace [OPTIONS] [COMMAND] [ARGS]...
Options:
--config TEXT Path to the metagit definition file
-h, --help Show this message and exit.
grep#
Search on-disk file contents across managed workspace repos.
Use metagit search for manifest metadata only. Matches under
node_modules, .venv, and similar scaffold paths are always excluded.
Usage:
metagit workspace grep [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
info#
Show ripgrep availability and workspace grep search backend.
Usage:
metagit workspace grep info [OPTIONS]
Options:
--json Print JSON for agents
-h, --help Show this message and exit.
search#
Search file contents (default when a QUERY argument is provided).
Usage:
metagit workspace grep search [OPTIONS] QUERY
Options:
-p, --project TEXT Limit search to a workspace project
-r, --repo TEXT Limit search to repo selector(s); repeatable
--preset TEXT Search preset (terraform, docker, infra, ci)
--intent TEXT Intent filter (config, scripts, ci, docker, terraform)
--limit INTEGER Maximum number of hits [default: 25]
-C INTEGER Context lines around matches [default: 0]
--files-with-matches Return matching file paths only
--json Print JSON for agents
-h, --help Show this message and exit.
health#
Workspace maintenance health (parity with MCP metagit_workspace_health_check).
Usage:
metagit workspace health [OPTIONS]
Options:
--json Print JSON for agents
-p, --project TEXT Limit health check to one project
--check-git-status / --no-git-status
[default: check-git-status]
--check-stale-branches / --no-stale-branches
[default: check-stale-branches]
--check-gitnexus / --no-gitnexus
[default: check-gitnexus]
--check-dependencies / --no-dependencies
[default: check-dependencies]
-h, --help Show this message and exit.
import#
Bulk-import repos from GitHub, GitLab, or Azure DevOps (additive + ensure).
Usage:
metagit workspace import [OPTIONS]
Options:
-p, --project TEXT Workspace project name to import into
[required]
--provider [github|gitlab|azure_devops]
Source provider [required]
--org TEXT GitHub organization
--user TEXT GitHub user
--group TEXT GitLab group path
--organization TEXT Azure DevOps organization
--ado-project TEXT Azure DevOps project filter
--ignore TEXT fnmatch denylist on provider full_name
(repeatable)
--include-pattern TEXT fnmatch allowlist on provider full_name
(repeatable)
--sync / --no-sync Clone or update repos after manifest apply
[default: no-sync]
--json Print JSON result (default for import alias)
[default: True]
-h, --help Show this message and exit.
list#
List workspace manifest summary, projects, and repository index.
Usage:
metagit workspace list [OPTIONS]
Options:
--json Print JSON for agents
--no-index Omit per-repo disk status from workspace list JSON
--include-workspace Embed the full workspace object (large umbrellas —
operator only)
--limit INTEGER Max repos_index rows. Use 0 for all rows (operator
only). [default: 80]
--offset INTEGER [default: 0]
-h, --help Show this message and exit.
project#
Manage workspace projects in the manifest.
Usage:
metagit workspace project [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
add#
Add a project to the workspace manifest.
Usage:
metagit workspace project add [OPTIONS] NAME
Options:
--description TEXT Project description
--agent-instructions TEXT Agent instructions for the project
--ensure Succeed without changes when the project already
exists with matching fields
--json Print JSON for agents
-h, --help Show this message and exit.
list#
List projects defined in the workspace manifest.
Usage:
metagit workspace project list [OPTIONS]
Options:
--json Print JSON for agents
-h, --help Show this message and exit.
remove#
Remove a project (and its repos) from the workspace manifest.
Usage:
metagit workspace project remove [OPTIONS] NAME
Options:
--force Remove protected projects
--json Print JSON for agents
-h, --help Show this message and exit.
rename#
Rename a workspace project (manifest and sync folder when present).
Usage:
metagit workspace project rename [OPTIONS] FROM_NAME TO_NAME
Options:
--dry-run Show planned manifest and disk steps without applying
--manifest-only Update .metagit.yml only; do not rename sync folders
--no-update-sessions Do not migrate .metagit/sessions project files
--force Overwrite existing targets
--json Print JSON for agents
-h, --help Show this message and exit.
repo#
Manage repository entries in the workspace manifest.
Usage:
metagit workspace repo [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
add#
Add a repository entry to a workspace project (manifest only).
Usage:
metagit workspace repo add [OPTIONS]
Options:
-p, --project TEXT Workspace project name [required]
-n, --name TEXT Repository name [required]
--description TEXT
--path TEXT Relative path under workspace root
--url TEXT Remote repository URL
--sync / --no-sync
--agent-instructions TEXT
--force Add repos to protected projects
--ensure Succeed without changes when the repo already
exists with matching url/path
--json Print JSON for agents
-h, --help Show this message and exit.
list#
List repositories in the workspace manifest.
Usage:
metagit workspace repo list [OPTIONS]
Options:
-p, --project TEXT Limit to one project name
--json Print JSON for agents
--detail [slim|full] slim omits agent instructions and components
[default: slim]
--limit INTEGER Max repo rows. Use 0 for all rows (operator only).
[default: 80]
--offset INTEGER [default: 0]
-h, --help Show this message and exit.
move#
Move a repository entry to another workspace project.
Usage:
metagit workspace repo move [OPTIONS]
Options:
-p, --project TEXT Source project [required]
-n, --name TEXT Repository name [required]
--to-project TEXT Target workspace project [required]
--dry-run
--manifest-only Update manifest only; do not move sync mount
--force
--json Print JSON for agents
-h, --help Show this message and exit.
remove#
Remove a repository entry from the workspace manifest (does not delete files).
Usage:
metagit workspace repo remove [OPTIONS]
Options:
-p, --project TEXT Workspace project name [required]
-n, --name TEXT Repository name [required]
--force Remove protected repos
--json Print JSON for agents
-h, --help Show this message and exit.
rename#
Rename a repository entry and its sync mount when present.
Usage:
metagit workspace repo rename [OPTIONS] FROM_NAME TO_NAME
Options:
-p, --project TEXT Workspace project name [required]
--dry-run
--manifest-only Update manifest only; do not rename sync mount
--force
--json Print JSON for agents
-h, --help Show this message and exit.
select#
Select project repo to work on
Usage:
metagit workspace select [OPTIONS]
Options:
-p, --project TEXT Project within workspace to select target paths from
--repo TEXT Open this repository in the default editor without the
picker TUI
-h, --help Show this message and exit.
summary#
Discovery readiness score for agent session start (RFC-0020).
Usage:
metagit workspace summary [OPTIONS]
Options:
--json Print JSON for agents
-p, --project TEXT Limit summary to one project
--include-cards Attach lean per-repo cards (default off —
token lean)
--include-coordination / --no-coordination
Include lightweight AOS/ACL/task hints when
available [default: include-coordination]
-h, --help Show this message and exit.
worktree#
Manage isolated agent git worktrees.
Usage:
metagit worktree [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
adopt#
Register an existing git worktree without creating another checkout.
Usage:
metagit worktree adopt [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT project/repo, or . / self for the definition repo
[required]
--path TEXT Existing worktree path from git worktree list [required]
--agent-id TEXT [required]
--task-id TEXT [required]
--branch TEXT Expected branch. Detached worktrees are refused.
--json
-h, --help Show this message and exit.
create#
Create an isolated worktree for an agent with an active lease.
Usage:
metagit worktree create [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT project/repo, or . / self for the definition repo
[required]
--agent-id TEXT [required]
--task-id TEXT [required]
--branch TEXT [required]
--lease-id TEXT
--integration-branch TEXT
--claim TEXT Optional claim pattern to record on manifest
--json
-h, --help Show this message and exit.
destroy#
Destroy an agent worktree.
Usage:
metagit worktree destroy [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--worktree-id TEXT
--agent-id TEXT
--repository TEXT project/repo, or . / self for the definition repo
--task-id TEXT Required when the agent has more than one worktree in
the repo
--force
--json
-h, --help Show this message and exit.
gc#
Garbage-collect worktrees with expired leases or missing paths.
Usage:
metagit worktree gc [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--force Remove checkouts that still have unsaved or unpushed work
--dry-run Report what would be destroyed or skipped
--json
-h, --help Show this message and exit.
list#
List worktree records.
Usage:
metagit worktree list [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--repository TEXT
--agent-id TEXT
--status TEXT
--json
-h, --help Show this message and exit.
manifest#
Show the agent execution manifest written on worktree create.
Usage:
metagit worktree manifest [OPTIONS] AGENT_ID
Options:
--definition TEXT [default: .metagit.yml]
--json
-h, --help Show this message and exit.
status#
Show git status summaries for active worktrees.
Usage:
metagit worktree status [OPTIONS]
Options:
--definition TEXT [default: .metagit.yml]
--worktree-id TEXT
--agent-id TEXT
--json
-h, --help Show this message and exit.
MCP Command Notes#
- Start MCP stdio runtime:
metagit mcp serve- Start against a specific workspace root:
metagit mcp serve --root /path/to/workspace- Print status snapshot and exit:
metagit mcp serve --status-once- Shared coordination state: export
METAGIT_STATE_URLand optionalMETAGIT_STATE_TOKENon the MCP server process beforemetagit mcp serveso objectives/handoffs/approvals/events use the remote ops backend. Verify viaresources/read→metagit://gate/status(state_backendfield). Skill:metagit-sharing-state. - When the workspace gate is active, the tool
metagit_repo_searchsearches only repos listed underworkspace.projects[].reposin.metagit.yml(tags, sync status, resolved paths). Optional filters:status[],has_url,sync_enabled,sort(score|project|name). Use query*for filter-only listing. Setpath_only: trueto resolve one absolute path (ok+path/project/repo, orok: falsewhen missing/ambiguous). metagit_workspace_searchsearches on-disk file contents (not manifest metadata). Uses ripgrep when available (repos,paths,exclude,context_lines,intent,include_paths). Always excludes scaffold paths (node_modules,.venv, etc.). Falls back to a bounded scanner ifrgis not installed.metagit_workspace_grep_inforeturnsripgrep_available,ripgrep_path,ripgrep_version, andsearch_backend(ripgreporpython_walk). CLI equivalent:metagit workspace grep info.metagit_workspace_syncbatch-syncs repos (repos: ["all"]or selectors), withonly_if(any|missing|dirty|behind_origin),max_parallel, anddry_run.metagit_cross_project_dependenciesmaps relationships from asource_projectusingdependency_types(declared,imports,shared_config,url_match,ref),depth, and per-repo GitNexusgraph_status(indexed|stale|missing).metagit_workspace_health_checkreturns per-repo git/GitNexus signals, optional staleness metrics (head_commit_age_days,merge_base_age_dayswhencheck_stale_branches), tunable thresholds (branch_head_warning_days,branch_head_critical_days,integration_stale_days), and prioritized recommendations (sync,analyze,clone,fix_config,review_branch_age,reconcile_integration, …).metagit_workspace_semantic_searchrunsnpx gitnexus query -r <registry>per selected repo (queryrequired; optionalrepos,task_context,goal,limit_per_repo,timeout_seconds) for GitNexus-ranked processes.metagit_workspace_discoverlists files byintentorpatternwith optionalcategorizegrouping (requiresintentorpattern).metagit_project_template_applypreviews or applies bundled templates fromsrc/metagit/data/templates/(dry_rundefault;confirm_applyrequired for writes).- Coordination (active gate):
metagit_objective_list,metagit_objective_upsert,metagit_objective_edit;metagit_approval_request,metagit_approval_list,metagit_approval_resolve;metagit_handoff_list,metagit_handoff_create,metagit_handoff_claim,metagit_handoff_complete;metagit_events(optionalsinceISO cursor; includessource=acllifecycle rows). All respectMETAGIT_STATE_URLwhen set on the MCP host. - ACL / Agent Coordination Layer (active gate):
metagit_branch_allocate,metagit_branch_list,metagit_branch_release;metagit_lease_acquire,metagit_lease_renew,metagit_lease_release,metagit_lease_list;metagit_worktree_create,metagit_worktree_destroy,metagit_worktree_status,metagit_worktree_list;metagit_claim_declare,metagit_claim_check,metagit_claim_list,metagit_claim_release. CLI:metagit branch|lease|worktree|claim. ACL branch leases are distinct from handoff claim TTL. See agent-coordination.md. - Resources: Start with
metagit://catalog. Phase 1–4 URIs includegate/status(includesstate_backenddiagnostics),workspace/map?limit=80,session/meta,session/digest,objectives,approvals/pending,handoffs/open,events/recent,prompt/catalog, dynamicprompt/{scope}/{kind},project/{project}/summary,repo/{project}/{repo}/card,workspace/config(summary default;?view=fullrefused above 80 repos unlessconfirm=1),workspace/repos/status?summary=1,workspace/health,workspace/context(alias). Spec: mcp-layered-resources-spec.md. Large umbrellas: context-reduction.md. Skills:metagit-mcp-resources,metagit-sharing-state. - Campaigns (active gate):
metagit_campaign_status(paged overlay summary),metagit_campaign_board_sync(Azure Boards WIT,dry_runfirst),metagit_campaign_context. Do not return the frozen_campaigns/*.ymldocument to the model. - Organization index (active gate):
metagit_org_index(organization, optionalrefresh/full),metagit_org_search(query/language/topic/has/stale_days),metagit_org_repo_get,metagit_graph_neighbors,metagit_org_repo_materialize(confirm: trueunlessdry_run). CLI:metagit org index github,metagit org search,metagit graph neighbors,metagit repo materialize. Observations stay in~/.metagit/indexes/github/; curated edges stay in.metagit.ymlgraph. See org-index.md. - Prompts capability:
prompts/listandprompts/get(names likeworkspace/session-start) mirror prompt resources. - Project context (active gate):
metagit_project_context_switch— set active workspace project; return repo branch/dirty summary, safe env exports (METAGIT_*), and restored session fields from.metagit/sessions/<project>.json.metagit_session_update— persistagent_notes,recent_repos, and non-secretenv_overridesbefore switching away.metagit_workspace_state_snapshot— write a git-state manifest to.metagit/snapshots/<id>.json(not a file copy).metagit_workspace_state_restore— reload snapshot metadata and optionally re-run context switch; does not reset git branches or uncommitted changes.
Workspace configuration#
Under workspace.projects[].repos, each repository entry may include a flat string-to-string tags map (for example tier: "1"). These tags are carried into the workspace index and into metagit search / metagit find for filtering.
Repository entries must use exactly one locator: path (local folder) or url (git remote).
Repo Locator Migration (path -> url)#
Promote path-based entries to git-managed clones when they should be reproducible across machines or used in CI.
Preview a promotion#
metagit project --project <project_name> repo promote --name <repo_name> --dry-run
Apply a promotion#
metagit project --project <project_name> repo promote --name <repo_name>metagit project --project <project_name> repo promote --name <repo_name> --url <git-url>
Validation after promotion#
metagit config validate --config-path .metagit.ymlmetagit project sync --project <project_name>metagit project repo list --project <project_name> --json
Common failures and fixes#
protected: rerun with--forceonly after approval.source_missing: fix or remove stale local path before promoting.no_url: pass--urlexplicitly or configure the source repo remote.invalid_url: supply a valid SSH/HTTPS git URL.duplicate_identity: remove or consolidate duplicate repo identity entries.sync_failed: rerunproject sync; inspect sync output and filesystem permissions.
Managed repository search#
metagit search QUERY— list managed repositories from the workspace definition that match the query (name, URL substring, tag keys/values, project name). Only repos declared underworkspace.projects[].reposare considered. Supports--status(repeatable) and--sort score|project|name.metagit find QUERY— alias formetagit search.--definition PATH—.metagit.ymlto load (default:.metagit.ymlin the current directory). The workspace root for resolvingpath:entries is the parent directory of that file.--json— print search results as JSON (matches includematch_reasonsand scores).--path-only— resolve to exactly one local directory (fails if there is no match or more than one match). MCP:metagit_repo_searchwithpath_only: true.--tag key=value— repeat to require matching tag values (all given pairs must match).--project,--exact,--synced-only, and--limitnarrow or rank results further.
Human navigation (metagit nav)#
metagit nav/metagit navigate— FuzzyFinder project then repo, then open the configured editor.--all— one FuzzyFinder over every managedproject/repo(ignores--project/--repo).--unmanaged— with--all, also list extra sync-folder directories (dimmed).--print-path— print the selected absolute path to stdout and skip the editor.- Disabled when
METAGIT_AGENT_MODEis set. Agents:metagit workspace repo list --jsonthenmetagit search QUERY --path-only.
Local JSON API (metagit api)#
metagit api serve— bind aThreadingHTTPServeron--host/--port(default127.0.0.1:7878) under--root(directory containing.metagit.yml).metagit api serve --status-once— allocate a port (use--port 0for ephemeral), printapi_state=ready host=… port=…, and exit (for tests and automation).GET /v1/repos/search?q=…— same managed-repo search as the CLI; optional query params:project,exact=true|false,synced_only=true|false,limit, repeattag=key=value.GET /v1/repos/resolve?q=…— single-match resolution; HTTP404when not found,409when ambiguous (body includesManagedRepoResolveResultJSON).GET /v2/workspace/grep?q=…— content grep across managed repos (optionalproject,repo,preset,intent,max_results,context_lines,include_paths). CLI equivalent:metagit workspace grep.GET /v2/workspace/grep/info— ripgrep availability and search backend. CLI equivalent:metagit workspace grep info.
Agent profile and campaigns#
Structured manifest fields and CLI groups for multi-agent coordination. Full reference: modality-feature-registry.md.
metagit agent apply— materialize mergedagent_profileblocks into vendor runtimes (--project,--repo,--target,--dry-run). See agent-profile.md.metagit agent profile show— print the effective merged profile for one repo.
metagit campaign—list,status,new,validate,set,expand,context, and optionaleverroomattach/status/sync for cross-project campaign YAML underworkspace.campaigns_path(default_campaigns/). See campaigns.md and campaign-everroom.md.
metagit context handoff— queue operations includingclaim --ttl,heartbeat, and auto-release of expired claims.metagit context events— optional--campaign/--objectivefilters when polling workspace events (includes ACLsource=aclrows).
metagit branch— allocate / release / cleanup / archive / listagent/*branches.metagit lease— acquire / renew / release / list ACL branch leases (not handoff claim TTL).metagit worktree— create / destroy / gc / status / list / manifest for isolated agent checkouts under.worktrees/.metagit claim— declare / check / list / release advisory file-path claims.- Full ACL reference: agent-coordination.md.
metagit agent dispatch-plan— includes profile skill hints, suggestedprofile_apply_command, andhandoff.acl_commandswhen project/repo are set.