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.

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
  --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.

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.

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
  --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:

  --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.

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.

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.

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
  -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.

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.
  -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|github_copilot]
                                  Explicit target to install (repeatable). If
                                  omitted, auto-detect targets.
  --disable-target [opencode|hermes|openclaw|claude_code|github_copilot]
                                  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
  --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
  --kind [monorepo|umbrella|application|gitops|infrastructure|service|library|website|other|docker_image|repository|cli]
                                  Project kind
  --ref TEXT                      Reference in the current project for the
                                  target project
  --path TEXT                     Local project path
  --url TEXT                      Repository URL
  --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
  --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.

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:

  -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:

  -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  [required]
  --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
  --apply / --no-apply            Apply computed changes to .metagit.yml
                                  [default: no-apply]
  --yes                           Confirm destructive reconcile removals
  -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
  -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|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|github_copilot]
                                  Explicit target to install (repeatable). If
                                  omitted, auto-detect targets.
  --disable-target [opencode|hermes|openclaw|claude_code|github_copilot]
                                  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.

version

Get the application version.

Usage:

metagit version [OPTIONS]

Options:

  -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.

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
  --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:

  --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
  --kind [monorepo|umbrella|application|gitops|infrastructure|service|library|website|other|docker_image|repository|cli]
  --path TEXT                     Relative path under workspace root
  --url TEXT                      Remote repository URL
  --sync / --no-sync
  --agent-instructions TEXT
  --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]
  --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
  -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
• When the workspace gate is active, the tool metagit_repo_search searches only repos listed under workspace.projects[].repos in .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_search uses ripgrep when available (repos, paths, exclude, context_lines, intent, include_paths). Falls back to a bounded scanner if rg is not installed.
• metagit_workspace_sync batch-syncs repos (repos: ["all"] or selectors), with only_if (any|missing|dirty|behind_origin), max_parallel, and dry_run.
• metagit_cross_project_dependencies maps relationships from a source_project using dependency_types (declared, imports, shared_config, url_match, ref), depth, and per-repo GitNexus graph_status (indexed|stale|missing).
• metagit_workspace_health_check returns per-repo git/GitNexus signals, optional staleness metrics (head_commit_age_days, merge_base_age_days when check_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_search runs npx gitnexus query -r <registry> per selected repo (query required; optional repos, task_context, goal, limit_per_repo, timeout_seconds) for GitNexus-ranked processes.
• metagit_workspace_discover lists files by intent or pattern with optional categorize grouping (requires intent or pattern).
• metagit_project_template_apply previews or applies bundled templates from src/metagit/data/templates/ (dry_run default; confirm_apply required for writes).
• Resources (active gate): metagit://workspace/health, metagit://workspace/context (active project session from .metagit/sessions/).
• 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 — persist agent_notes, recent_repos, and non-secret env_overrides before 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 under workspace.projects[].repos are considered. Supports --status (repeatable) and --sort score|project|name.
• metagit find QUERY — alias for metagit search.
• --definition PATH — .metagit.yml to load (default: .metagit.yml in the current directory). The workspace root for resolving path: entries is the parent directory of that file.
• --json — print search results as JSON (matches include match_reasons and 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 --limit narrow or rank results further.

Local JSON API (metagit api)

• metagit api serve — bind a ThreadingHTTPServer on --host / --port (default 127.0.0.1:7878) under --root (directory containing .metagit.yml).
• metagit api serve --status-once — allocate a port (use --port 0 for ephemeral), print api_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, repeat tag=key=value.
• GET /v1/repos/resolve?q=… — single-match resolution; HTTP 404 when not found, 409 when ambiguous (body includes ManagedRepoResolveResult JSON).