> ## 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.

# Global Settings

> Configure storage paths, symlinks, desktop integration, and download behavior globally.

The global configuration file applies default settings to all managed apps. You can override any of these settings per app inside an [app recipe](/configuration/app-recipes).

## File location

```
~/.config/fp-appimage-updater/config.yml
```

Generate a starter file with:

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

## Example

```yaml theme={null}
storage_dir: ~/.local/bin/AppImages
symlink_dir: ~/.local/bin
naming_format: '{name}.AppImage'
manage_desktop_files: true
create_symlinks: false
segmented_downloads: true
show_all: false
respect_rate_limits: true
github_proxy: true
github_proxy_prefix: https://gh-proxy.com/
```

## GitHub Rate Limits & Tokens

GitHub imposes rate limits on its REST API for unauthenticated requests (60 requests per hour per IP). To bypass this, you can provide a personal access token (PAT), which increases your limit to 5,000 requests per hour.

### Configuration methods

fp-appimage-updater checks for a token in the following order:

1. **Environment Variable:** Set the `GITHUB_TOKEN` environment variable in your shell or service manager.
2. **Secrets File:** Create a `secrets.yml` file in your config directory. This is the recommended method for dotfile users who want to keep secrets separate from general configuration for easier encryption.
3. **Global Config:** You can also place `github_token` directly in `config.yml`, though this is discouraged for security reasons.

### Using secrets.yml

Create the file at `~/.config/fp-appimage-updater/secrets.yml`:

```yaml theme={null}
github_token: ghp_your_secret_token_here
```

<Note>
  Tokens are only sent to `api.github.com`. They are **never** shared with third-party GitHub proxies configured via `github_proxy_prefix`.
</Note>

## Fields

<ParamField path="storage_dir" type="string" default="~/.local/bin/AppImages">
  Directory where downloaded AppImage files are stored.
</ParamField>

<ParamField path="symlink_dir" type="string" default="~/.local/bin">
  Directory where symlinks to installed AppImages are created. Only used when `create_symlinks` is `true`.
</ParamField>

<ParamField path="naming_format" type="string" default="{name}.AppImage">
  Filename template for stored AppImages. Supported placeholders:

  * `{name}`: Replaced with the app's `name` field from its recipe.
  * `{version}`: Replaced with the resolved version of the app (e.g., `1.2.3`).
</ParamField>

<ParamField path="manage_desktop_files" type="boolean" default="true">
  When enabled, fp-appimage-updater automatically extracts `.desktop` manifests and icons from the AppImage and installs them into `~/.local/share/applications` and `~/.local/share/icons`.
</ParamField>

<ParamField path="create_symlinks" type="boolean" default="false">
  When enabled, creates a symlink in `symlink_dir` pointing to the installed AppImage. Useful for putting AppImages on your `PATH` without modifying `storage_dir`.
</ParamField>

<ParamField path="segmented_downloads" type="boolean" default="true">
  Splits downloads into parallel HTTP range requests when the server supports it. Speeds up large AppImage downloads on capable servers.
</ParamField>

<ParamField path="show_all" type="boolean" default="false">
  When enabled, `update` includes apps that are already up to date in its output. By default, only apps that were updated, rate-limited, or failed are shown.
</ParamField>

<ParamField path="respect_rate_limits" type="boolean" default="true">
  When enabled, apps that hit a provider rate limit are skipped on subsequent runs until the retry window expires. Set to `false` to always attempt the request regardless of a prior rate limit.
</ParamField>

<ParamField path="github_proxy" type="boolean" default="true">
  Enables the GitHub API proxy fallback. When a GitHub release API request is rate limited, fp-appimage-updater retries through the configured proxy bases. The actual AppImage download always uses the direct GitHub asset URL — only metadata lookups are proxied.
</ParamField>

<ParamField path="github_proxy_prefix" type="string | string[]" default="all">
  Proxy base URL(s) to use when `github_proxy` is enabled. Accepts a single URL string, a YAML list of URLs, or the string `all` to try every built-in proxy in order.

  ```yaml theme={null}
  # Single proxy
  github_proxy_prefix: "https://gh-proxy.com/"

  # Multiple proxies tried in order
  github_proxy_prefix:
    - "https://gh-proxy.com/"
    - "https://corsproxy.io/?"
    - "https://api.allorigins.win/raw?url="

  # Try all built-in proxies
  github_proxy_prefix: all
  ```
</ParamField>

## Self-hosted forge URL overrides

These optional fields let you point fp-appimage-updater at a self-hosted GitHub or GitLab instance instead of the public APIs.

<ParamField path="github_release_api_url" type="string">
  Override the GitHub REST API base URL. Useful when your apps are hosted on GitHub Enterprise Server.
</ParamField>

<ParamField path="github_release_web_url" type="string">
  Override the GitHub web base URL used to construct release page links.
</ParamField>

<ParamField path="gitlab_release_api_url" type="string">
  Override the GitLab API base URL. Set this when your apps live on a self-managed GitLab instance.
</ParamField>

<ParamField path="gitlab_release_web_url" type="string">
  Override the GitLab web base URL used to construct release page links.
</ParamField>

<Note>
  Every field in `config.yml` can be overridden for a specific app inside its recipe file. App-level settings always take precedence over the global config. See [app recipes](/configuration/app-recipes) for the full list of per-app overrides.
</Note>