> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.fpt.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostic Tool (doctor)

> Run health checks to diagnose configuration and tooling issues.

<Tip>
  Run `doctor` first whenever you experience unexpected behavior. It quickly surfaces missing directories, unparseable recipes, a stale lockfile, and absent tooling before you dig deeper.
</Tip>

The `doctor` command inspects your local setup and reports the status of each check:

```bash theme={null}
fp-appimage-updater doctor
```

## Checks performed

| Check                 | What it verifies                                          |
| --------------------- | --------------------------------------------------------- |
| `config_dir`          | The configuration directory exists                        |
| `apps_dir`            | The apps subdirectory exists                              |
| `global_config`       | The global `config.yml` file is present and parseable     |
| `state_dir`           | The state directory is accessible                         |
| `parsed_app_recipes`  | Number of recipe files that loaded successfully           |
| `invalid_app_recipes` | Number of recipe files that failed to parse               |
| `process_lock`        | Whether the current lockfile is missing, active, or stale |
| `github_api`          | GitHub API connectivity and token validity                |

Each check reports either `ok` or `warn`. A `warn` result does not stop the tool from running, but it may explain unexpected behavior.

`process_lock` reports `warn` when the lockfile looks stale or malformed. That usually means a previous run exited unexpectedly, and the next run can clean it up.

`doctor` checks local files, local tools, and performs a lightweight request to the GitHub API to verify your rate limit and token status.

<Note>
  Add `--json` to get machine-readable output suitable for scripting or monitoring:

  ```bash theme={null}
  fp-appimage-updater doctor --json
  ```
</Note>

## Common issues

**Recipe files failed to parse**

Run `validate` to identify which files have errors and what the parse error is:

```bash theme={null}
fp-appimage-updater validate
```

To check a single recipe by name:

```bash theme={null}
fp-appimage-updater validate <app-name>
```

***

**Config directory not found**

Initialize the configuration directory with:

```bash theme={null}
fp-appimage-updater init --global
```

This creates the expected directory structure and a starter `config.yml`.