metagit-cli

Files (2)

• SKILL.md
• SKILL.md · metagit-cli/

SKILL.md (first lines)

# Metagit CLI (agent shortcuts)

Use this skill when an agent should drive metagit **only through the `metagit` command**. Do not call MCP tools or `metagit api` from workflows covered here unless the user explicitly asks.

Set non-interactive defaults when automating:

```bash
export METAGIT_AGENT_MODE=true
```

**Token hygiene:** do not dump `detect` yaml/json, `config example`, or a full umbrella `.metagit.yml` into context. Prefer `-o summary`. Write full detect payloads with `--output-file .metagit/.detect/…`. Never run `metagit detect repo_map`. Bootstrap with `metagit init --kind application --no-prompt` (see `metagit-bootstrap`).

<!-- modality:context_reduction -->
<!-- modality:campaign_board_link -->

Agents: `metagit config show --json` refuses above 80 repos unless `--confirm-full`. `workspace list --json` omits `summary.workspace` unless `--include-workspace`. Maps/lists are paged (default 80). Large umbrellas: `metagit prompt workspace -k large-workspace --text-only`.

**Session start** (from umbrella repo with `.metagit.yml`):

```bash
metagit context pack --tier 0 --json
metagit prompt workspace -k session-start --text-only -c .metagit.yml
```

Repo-root agent docs: [AGENTS.md](https://github.com/metagit-ai/metagit-cli/blob/main/AGENTS.md) · [llms.txt](https://github.com/metagit-ai/metagit-cli/blob/main/llms.txt) · [docs/agents.md](https://metagit-ai.github.io/metagit-cli/agents/).

<!-- modality:nav_flattened -->
<!-- modality:managed_repo_search -->

## Navigate a target (copy/paste)

Do **not** call `metagit nav` (human FuzzyFinder; rejected in `METAGIT_AGENT_MODE`).

```bash
# 1. List every managed project/repo + path
metagit workspace repo list -c .metagit.yml --json
# MCP: metagit_workspace_repos_list

# 2. Resolve one absolute path (fails if the query is ambiguous)
cd "$(metagit search '<repo>' -c .metagit.yml --path-only)"
# MCP: metagit_repo_search { "query": "<repo>", "path_only": true }
```

Humans: `metagit nav --all` (optional `--unmanaged`, `--print-path`).

Global flags (most commands):

- `metagit -c path/to/metagit.config.yaml` — **appconfig** only (default `metagit.config.yaml`)
- Workspace manifest: `-c .metagit.yml` on `metagit config …`, `metagit workspace …`, and leaf `config graph suggest|export -c …`
- Workspace manifest on the coordination families (`branch`, `lease`, `worktree`, `claim`, `task`, `semantic`, `merge`, `schedule`, `aos`): `--definition .metagit.yml` — these commands expose **no `-c`**
- `--workspace-root` on graph suggest — checkout root used to **scan** inferred deps (default: appconfig `workspace.path`); not the manifest path

---

## Manifest editing fast map (`.metagit.yml`)

Use this table first when changing a workspace manifest from the CLI. Prefer **catalog commands** for projects/repos; use **`config patch`** for everything else in the schema (documentation, graph, dedupe overrides, nested fields).

| Task | Command |
|------|---------|
| **Inspect** manifest on disk | `metagit config show -c .metagit.yml` |
| **Inspect** normalized model | `metagit config show -c .metagit.yml --normalized` |
| **Inspect** as JSON (agents) | `metagit config show -c .metagit.yml --json` (refused on large umbrellas unless `--confirm-full`) |
| **Browse** fields / paths | `metagit config tree -c .metagit.yml` or `… --json` |
| **Validate** after edits | `metagit config validate -c .metagit.yml` |
| **Dry-run** schema change | `metagit config preview -c .metagit.yml --file ops.json` |
| **Apply** schema change | `metagit config patch -c .metagit.yml --file ops.json --save` |
| **Set one field** | `metagit config patch -c .metagit.yml --op set --path <path> --value <v> --save` |
| **Enable** optional block | `metagit config patch … --op enable --path <path> --save` |
| **Add list item** | `metagit config patch … --op append --path <list.path> --save` then `set` on `[index].field` |
| **Remove list item** | `metagit config patch … --op remove --path <list.path>[index] --save` |
| **Split** into per-project files | `metagit config split -c .metagit.yml --by all --dir .metagit.d` |
| **Preview** a split | `metagit config split -c .metagit.yml --by all --dry-run` |
| **Flatten** includes to one file | `metagit config flatten -c .metagit.yml` |
| **Show** the root file when split | `metagit config show -c .metagit.yml --source` |

When `.metagit.yml` contains `includes:`, edit the fragment that owns the project or graph entry (`.metagit.d/projects/<name>.yml`, or the graph fragment). Do not paste a merged manifest over the root. `metagit config validate` reports errors as `fragment:line`. `metagit fmt -c .metagit.yml` formats the root and every fragment. Older metagit releases reject `includes` (`Extra inputs are not permitted`).

### Catalog shortcuts (projects & repos)

| Task | Command |
|------|---------|
| List projects | `metagit workspace project list -c .metagit.yml --json` |
| List repos (all / one project) | `metagit workspace repo list -c .metagit.yml --json` / `… --project <p> --json` |
| Add project | `metagit workspace project add -c .metagit.yml --name <p> --json` |
| Remove project | `metagit workspace project remove -c .metagit.yml --name <p> --json` |
| Rename project (dry-run) | `metagit workspace project rename -c .metagit.yml --name <old> --new-name <new> --dry-run --json` |
| Add repo | `metagit workspace repo add -c .metagit.yml --project <p> --name <r> (--url <url> | --path <path>) --json` |
| Remove repo (manifest only) | `metagit workspace repo remove -c .metagit.yml --project <p> --name <r> --json` |
| Rename / move repo (dry-run) | `metagit workspace repo rename …` / `metagit workspace repo move … --dry-run --json` |
| Search before adding | `metagit search "<name>" -c .metagit.yml --json` |

Active project context (optional): `metagit project repo add --name <r> (--url <url> | --path <path>)` after `metagit project select`.

For `workspace.projects[].repos[]`, use `--url` for git-backed entries and `--path` for local-folder entries.

### Schema patch examples (`ops.json`)

Paths use dot/bracket notation (same as web Config Studio). `--value` accepts JSON for objects.

```json
{
  "operations": [
    { "op": "set", "path": "name", "value": "my-workspace" },
    { "op": "enable", "path": "documentation" },
    { "op": "append", "path": "documentation" },
    { "op": "set", "path": "documentation[0]", "value": { "kind": "markdown", "path": "AGENTS.md" } },
    { "op": "enable", "path": "graph" },
    { "op": "append", "path": "graph.relationships" },
    {
      "op": "set",
      "path": "graph.relationships[0]",
      "value": {
        "id": "api-depends-infra",
        "from": { "project": "platform", "repo": "api" },
        "to": { "project": "infra", "repo": "terraform" },
        "type": "depends_on"
      }
    },
    { "op": "set", "path": "workspace.projects[0].dedupe.enabled", "value": false }

From metagit-ai/metagit-cli, MIT.

More from metagit-ai/metagit-cli