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

# Frequently Asked Questions

> Answers to common questions about fp-appimage-updater.

<AccordionGroup>
  <Accordion title="Do I need root or sudo to use fp-appimage-updater?">
    No. fp-appimage-updater operates entirely in user-space. All files — AppImages, symlinks, desktop entries, and icons — go under `~/.local/`. You only need `sudo` if you choose to install the tool itself system-wide using the `--system` flag during installation.
  </Accordion>

  <Accordion title="Can I use it on an immutable or atomic Linux distribution?">
    Yes. fp-appimage-updater is designed to work on immutable distributions like Fedora Silverblue and openSUSE MicroOS. All runtime files are written to user-space paths. If you attempt a system-wide install (`--system`) on a strictly immutable environment, the install script will reject the request.
  </Accordion>

  <Accordion title="How do I stop fp-appimage-updater from updating a specific app automatically?">
    Set `ignore: true` in the recipe to keep the app in your config while skipping it in `check` and `update`.

    If you want to keep the recipe but skip rate-limit cooldowns, set `respect_rate_limits: false` globally in `config.yml` or per-app in the recipe:

    ```yaml theme={null}
    respect_rate_limits: false
    ```
  </Accordion>

  <Accordion title="What happens to my AppImage if an update fails mid-download?">
    The existing AppImage is not replaced until the download completes successfully. A failed or interrupted download leaves the current version intact.
  </Accordion>

  <Accordion title="Does fp-appimage-updater have a GUI?">
    No — it is an intentional CLI-only tool and will never have a GUI.
  </Accordion>

  <Accordion title="How do I update fp-appimage-updater itself?">
    Run the `self-update` command:

    ```bash theme={null}
    fp-appimage-updater self-update
    ```

    To fetch a pre-release version, add `--pre-release`:

    ```bash theme={null}
    fp-appimage-updater self-update --pre-release
    ```
  </Accordion>

  <Accordion title="Can I use a custom configuration directory?">
    Yes. Pass `-c` or `--config` before any subcommand to override the default `~/.config/fp-appimage-updater/` path:

    ```bash theme={null}
    fp-appimage-updater -c /path/to/my-config check
    ```

    This flag works with every command.
  </Accordion>

  <Accordion title="Where does fp-appimage-updater remember what I already installed?">
    It keeps a small cache in `~/.local/state/fp-appimage-updater/cache.json`. That file stores the last known version, download metadata, the installed file path, and any rate-limit or capability hints from the previous run.

    If the cache is missing, fp-appimage-updater rebuilds it the next time you run `check` or `update`.
  </Accordion>

  <Accordion title="What is the zsync field in an app recipe?">
    The `zsync` field enables delta updates, which download only the bytes that changed instead of the full AppImage. Set it to `true` to derive the `.zsync` URL from the resolved download URL, or provide an explicit URL:

    ```yaml theme={null}
    zsync: true
    ```

    ```yaml theme={null}
    zsync: "https://example.com/app.AppImage.zsync"
    ```

    fp-appimage-updater uses its built-in `zsync-rs` backend for this, so you do not need to install a separate `zsync` system package. It only uses the delta path when it already has a local AppImage to compare against, and it falls back to the normal download path if the delta update cannot run.
  </Accordion>

  <Accordion title="Why is an app being skipped during updates?">
    The app may have been rate-limited on a previous run. When a rate limit is hit, fp-appimage-updater records the retry window and skips that app on subsequent runs until the window expires.

    Check the current status of a specific app:

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

    To disable this behavior globally, set `respect_rate_limits: false` in your `config.yml`. You can also set it per-app in the recipe file.
  </Accordion>

  <Accordion title="Can I define multiple apps that come from the same repository?">
    Yes. Each recipe must have a unique `name` field, but multiple recipes can point to different assets from the same repository. As long as each recipe has a distinct `name` and its `asset_match` pattern selects a different file, they are managed independently.
  </Accordion>
</AccordionGroup>