Skip to content

Installation and usage guide#

This guide covers practical ways to install and run Metagit locally, plus how to enable project skills for AI-agent workflows.

Requirements#

  • Python 3.12+
  • uv
  • git

Optional:

  • Docker (for container usage)
  • gitleaks (for local security checks in QA workflows)

Install Metagit globally as a tool:

uv tool install metagit-cli

Upgrade later:

uv tool install -U metagit-cli

Or let Metagit upgrade itself (dry-run by default):

metagit version upgrade
metagit version upgrade --apply

Verify:

metagit version
metagit --help

Shell tab completion#

Metagit ships first-class shell completion for zsh, bash, and fish. Static commands and flags are completed automatically; when a .metagit.yml is present, --project, --repo, and repomix --profile values are completed from the manifest and bundled profiles.

Install (writes to the conventional user path):

metagit completion install --shell zsh
metagit completion install --shell bash
metagit completion install --shell fish

Print a script or one-line activation hint:

metagit completion show --shell zsh
metagit completion install --shell zsh --stdout

Verify the callback works:

metagit completion doctor

zsh: ensure the install path is on fpath before compinit (the install command prints the exact line). After upgrading metagit, re-run completion install if new subcommands were added.

Option 2: install from source (local development)#

Clone and bootstrap:

git clone https://github.com/metagit-ai/metagit-cli.git
cd metagit-cli
uv sync

Install as an editable local package:

uv pip install -e .

Build a wheel and install that wheel:

task build
uv tool install dist/metagit-*-py3-none-any.whl

Option 3: container usage#

Run via container image:

docker pull ghcr.io/metagit-ai/metagit-cli:latest
docker run --rm ghcr.io/metagit-ai/metagit-cli:latest --help

First local use#

In a target Git repository:

metagit init --list-templates          # bundled profiles (application, umbrella, hermes-orchestrator, …)
metagit init ./my-coordinator --template hermes-orchestrator --create
metagit init --target ../hermes-control-plane --template hermes-orchestrator --no-prompt \
  --answers-file examples/hermes-orchestrator/answers.example.yml
metagit init --kind service --minimal  # any ProjectKind without a bundled template

This creates .metagit.yml and updates .gitignore.

Useful first checks:

metagit config validate
metagit info
metagit fmt

metagit format is an alias for metagit fmt. Formatting preserves YAML comments, injects a top-level # yaml-language-server: $schema=… directive, and uses two-space indentation. Use --check in CI to fail when YAML is not normalized; --target metagit|appconfig|all selects which file(s) to rewrite.

Local MCP runtime usage#

Start MCP runtime in current workspace:

metagit mcp serve

Run one-shot status snapshot:

metagit mcp serve --status-once

Pin a specific workspace root:

metagit mcp serve --root /path/to/workspace

AI-agent skill setup for this project#

If you cloned this repository and want skills available for local agent discovery:

task skills:sync
task generate:schema

One-shot combined:

task skills:sync generate:schema

This syncs project skills into .cursor/skills/ and regenerates config schemas.

Session closeout checks#

Before push or hand-off:

task skills:sync generate:schema
task qa:prepush

Troubleshooting#

  • If metagit fails after tool install, reinstall:
  • uv tool install -U --reinstall metagit-cli
  • If command not found, ensure uv tool bin path is on PATH.
  • If provider-backed features fail, configure API tokens in app config or environment:
  • METAGIT_GITHUB_API_TOKEN
  • METAGIT_GITLAB_API_TOKEN