> ## Documentation Index
> Fetch the complete documentation index at: https://getgat.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# gat system
> Inspect, repair, or clean internals and local cache state.
`gat system` is **Experimental**: its interface or behavior may change or be removed between releases. See [Feature lifecycle](/references/feature-lifecycle).
Inspect and maintain local repository state with these experimental commands.
| Command | Purpose |
| --------- | ------------------------------------------------------------------------------------------- |
| `inspect` | Read-only checks of lock, state, cache, and Git integration. |
| `repair` | Restore repository consistency. |
| `clean` | Remove disposable state. Explicit purge flags can delete cached objects or temporary files. |
Purging cached objects can remove your only copy of unpublished content.
Upload or back up needed objects before using `--purge-objects`.
For missing working files or damaged cached content, start with
[missing and corrupted objects](/concepts/automatic-sync#missing-and-corrupted-objects).
To remove unneeded stored content using history-based protection, see [gat gc](/commands/gc).
## Usage
```text theme={null}
Usage: gat system
```
```text theme={null}
Usage: gat system
Commands:
inspect Read-only inspection of Gat-managed maintenance state. Never writes
or repairs anything; reports actionable findings only
repair Restore invariants deliberately: recover authoritative `gat.lock`
state only via an explicit recovery choice, and rebuild derived state
(`SQLite` mirrors, cache metadata, managed Git excludes) when needed.
Omit the scope to target every domain
clean Remove only state proven disposable: completed transaction scratch,
abandoned temporary cache files, stale Gat-managed Git artifacts, and
other cleanup that never makes an authoritative recovery choice. Omit
the scope to target every domain
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
```
## Subcommands
## gat system clean
Remove disposable state. Purge flags also remove unverified temporary files or cached objects.
### Usage
```text theme={null}
Usage: gat system clean [OPTIONS] [SCOPE]
```
```text theme={null}
Usage: gat system clean [OPTIONS] [SCOPE]
Arguments:
[SCOPE]
Maintenance domain to clean (`all` by default)
[possible values: lock, state, cache, git, all]
Options:
--purge-temporary
Also remove unverified `tmp-*` cache ingest scratch files, in addition
to the ordinary proven-safe cleanup `gat system clean` does by
default. Gat cannot tell an abandoned temp file apart from one an
in-progress `add`/`fetch` on this or another process sharing the cache
is still writing, so this is an explicit, destructive opt-in: it can
disrupt another process's in-progress ingest. Never implied by `all`
--purge-objects
Also empty Gat's content-object fan-out namespace under the local
cache, in addition to the ordinary disposable temporary cache state
`gat system clean` removes by default. All locally cached objects are
removed and may need to be fetched/rebuilt again. Never implied by
`all`; must be opted into explicitly
-h, --help
Print help (see a summary with '-h')
```
### Examples
Remove only state Gat can prove is disposable.
```sh theme={null}
gat system clean
```
Explicitly remove unverified ingest scratch files.
```sh theme={null}
gat system clean cache --purge-temporary
```
This deletes cached objects, including unpublished content. Upload or back up needed objects first.
```sh theme={null}
gat system clean cache --purge-objects
```
## gat system inspect
Check repository state without changing it. Omit the domain to inspect all domains.
### Usage
```text theme={null}
Usage: gat system inspect [SCOPE]
```
```text theme={null}
Usage: gat system inspect [SCOPE]
Arguments:
[SCOPE]
Maintenance domain to inspect (`all` by default)
[possible values: lock, state, cache, git, all]
Options:
-h, --help
Print help (see a summary with '-h')
```
### Examples
Inspect lock, state, cache, and Git integration.
```sh theme={null}
gat system inspect
```
Restrict inspection to the cache domain.
```sh theme={null}
gat system inspect cache
```
## gat system repair
Repair the selected repository domain. Review inspection results before choosing recovery options.
### Usage
```text theme={null}
Usage: gat system repair [OPTIONS] [SCOPE]
```
```text theme={null}
Usage: gat system repair [OPTIONS] [SCOPE]
Arguments:
[SCOPE]
Maintenance domain to repair (`all` by default)
[possible values: lock, state, cache, git, all]
Options:
--restore-backup
Explicitly restore the validated backup representation left by an
interrupted `gat.lock` reshape (`.gat/lock-reshape//backup`)
instead of promoting the staged target. Only meaningful with `gat
system repair lock`
--promote-staged
Explicitly promote the validated staged `gat.lock` target left by an
interrupted reshape (`.gat/lock-reshape//new`) instead of
restoring the backup. Only meaningful with `gat system repair lock`
--transaction
Which interrupted `gat.lock` reshape transaction id to recover when
more than one exists under `.gat/lock-reshape/`. Only meaningful with
`gat system repair lock`
-h, --help
Print help (see a summary with '-h')
```
### Examples
Rebuild derived repository state.
```sh theme={null}
gat system repair state
```
Choose the validated backup during explicit lock recovery.
```sh theme={null}
gat system repair lock --restore-backup
```