# Workspace: multi-repo commands

Manage repos in a repowise workspace: list, add, remove, scan, set the default, explain contract links, lint architecture rules and read architecture metrics.

A **workspace** is a parent directory containing several git repos.
Indexing them together gives you cross-repo co-changes, API contract
matching, and federated MCP queries. See
[Workspace setup](https://docs.repowise.dev/multi-repo/workspace-setup) for the concept.

## `repowise workspace list`

Show all repos in the workspace with their indexing status.

```bash
repowise workspace list [PATH]
```

---

## `repowise workspace add`

Add a repo to the workspace. PATH can be relative or absolute. By default
the repo is indexed and its documentation is built from code, with no model
calls, so it never spends.

```bash
repowise workspace add PATH [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--alias` | string |  | Short name for the repo. Defaults to the directory name. |
| `--index / --no-index` | boolean | `true` | Run the index pipeline. |
| `--docs / --no-docs` | boolean |  | --docs: documentation written by a model (the primary repo's provider, or --provider). --no-docs: index only. Default: documentation built from code, no model calls and no key. Ignored with --no-index. |
| `--provider` | string |  | Override the inherited provider (defaults to the primary repo's config.yaml). |
| `--model` | string |  | Override the inherited model. |
| `--concurrency` | number |  | Max concurrent LLM calls for this repo's generation. |
| `--save-key / --no-save-key` | boolean | `true` | Save the provider API key this run authenticated with into the added repo's .repowise/.env (gitignored), so its MCP server can answer. |

```bash
repowise workspace add ../backend
repowise workspace add ../backend --alias backend-api
repowise workspace add ../mobile --no-docs            # index only, no documentation
repowise workspace add ../billing --docs              # documentation written by a model
repowise workspace add ../shared --no-index           # register only
```

---

## `repowise workspace remove`

Remove a repo from the workspace config. The repo's `.repowise/`
directory is preserved on disk; only the workspace entry is dropped.

```bash
repowise workspace remove ALIAS
```

---

## `repowise workspace scan`

Scan the workspace root for new git repos not yet in the config.

```bash
repowise workspace scan [PATH] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--yes / -y` | boolean | `false` | Auto-add every discovered repo without prompting. |

```bash
repowise workspace scan
repowise workspace scan --yes
```

---

## `repowise workspace set-default`

Change the default (primary) repo. The default is what tools target
when you omit `repo=` in MCP calls or don't pass `--repo` to the CLI.

```bash
repowise workspace set-default ALIAS
```

---

## `repowise workspace update`

Update stale repos and the cross-repo analysis. Same as
`repowise update --workspace`. `--repo ALIAS` updates one repo,
`--index-only` skips model-written documentation, `--dry-run` shows the
affected pages. See
[Updating](https://docs.repowise.dev/multi-repo/workspace-setup#updating).

```bash
repowise workspace update
repowise workspace update --repo backend
```

---

## `repowise workspace diagnostics`

Explain the cross-repo contract link count: per-repo provider and
consumer counts, unmatched consumers grouped by reason, and orphan
providers. See
[Extraction diagnostics](https://docs.repowise.dev/multi-repo/system-map#extraction-diagnostics).

```bash
repowise workspace diagnostics                    # human-readable report
repowise workspace diagnostics --format json      # raw JSON
repowise workspace diagnostics --repo api         # limit to one repo
```

The report names dangling calls, says which HTTP calls linked, and counts
unresolved topic names and files that call out with no recognised contract.

> **Note**
>
> `--json` still works as a deprecated alias for `--format json`. Use the
> canonical form in new scripts.

---

## `repowise workspace check`

Architecture lint: check the declared `conformance:` rules against the
system graph and detect dependency cycles. Exits non-zero on any
finding, so it gates CI. See
[Architecture conformance](https://docs.repowise.dev/multi-repo/conformance).

```bash
repowise workspace check                   # human-readable report; exit 1 on findings
repowise workspace check --format json     # raw report JSON
```

Cycle totals past the enumeration bound read "at least N". A graph with too
little evidence says so instead of reporting zero findings.

---

## `repowise workspace metrics`

Architecture-complexity metrics: propagation cost, the cyclic core,
per-service roles, and a deterministic 1-10 architecture score. See
[Architecture metrics](https://docs.repowise.dev/multi-repo/architecture-metrics).

```bash
repowise workspace metrics                 # human-readable summary
repowise workspace metrics --format json   # raw metrics JSON
```

The estate as a document (system map, contracts, dangling calls, health,
riskiest seams) is [`repowise report estate`](https://docs.repowise.dev/cli/changes#repowise-report).

> **Note**
>
> Most workspace-aware operations live on other commands:
> `repowise update --workspace`, `repowise watch -w`,
> `repowise hook install --workspace`, `repowise generate-claude-md -w`.