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.
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.
campaign#
Manage cross-project campaign overlays (default directory: _campaigns/).
Usage:
metagit campaign [OPTIONS] [COMMAND] [ARGS]...
Options:
-h, --help Show this message and exit.
expand#
Generate one spine objective per matching campaign repo.
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.
--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.
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).
[required]
--tag TEXT Optional tag filter during selection.
--objective-id TEXT Optional spine objective id to bind.
--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.
--definition TEXT [default: .metagit.yml]
--json Emit machine-readable JSON.
-h, --help Show this message and exit.
status#
Show detailed campaign status and repo rollup.
Usage:
metagit campaign 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.
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.
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.
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:
--workspace-root TEXT Workspace root (default: appconfig
workspace.path)
--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:
--workspace-root TEXT Workspace root (default: appconfig
workspace.path)
--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
--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
-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.
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.
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
-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 (tier 1+)
--repo TEXT Limit cards (tier 1+)
--json Print ContextPackResult as JSON
--max-tokens INTEGER RANGE Optional token budget for context pack with
greedy drops [x>=1]
-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.
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.
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]
-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]
-h, --help Show this message and exit.
repo_map#
Create a map of files and folders in a repository for further analysis.
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]
-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]
-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)
--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.
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.
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 local project config 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.
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.
list#
List project configuration (YAML, JSON, or all projects).
Usage:
metagit project list [OPTIONS]
Options:
--all List all workspace projects (catalog view) instead of one
project YAML
--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.
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] 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
--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|graph-discover|graph-maintain|health-preflight|instructions|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.
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.
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 local project config 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.
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.
import#
Bulk-import repos from a GitHub org/user or GitLab group (additive + ensure).
Usage:
metagit workspace import [OPTIONS]
Options:
-p, --project TEXT Workspace project name to import into
[required]
--provider [github|gitlab] Source provider [required]
--org TEXT GitHub organization
--user TEXT GitHub user
--group TEXT GitLab group path
--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
-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
-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.
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. 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). All respectMETAGIT_STATE_URLwhen set on the MCP host. - Resources: Start with
metagit://catalog. Phase 1–4 URIs includegate/status(includesstate_backenddiagnostics),workspace/map,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),workspace/repos/status?summary=1,workspace/health,workspace/context(alias). Spec: mcp-layered-resources-spec.md. Skills:metagit-mcp-resources,metagit-sharing-state. - 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.
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).--tag key=value— repeat to require matching tag values (all given pairs must match).--project,--exact,--synced-only, and--limitnarrow or rank results further.
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,expandfor cross-project campaign YAML underworkspace.campaigns_path(default_campaigns/). See campaigns.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.
metagit agent dispatch-plan— includes profile skill hints and suggestedprofile_apply_commandwhen profiles are configured.