Metadata-Version: 2.4
Name: aim-appimage-manager
Version: 0.1.0
Summary: A lightweight CLI for installing and managing AppImages on Linux.
Author: Leon Francis
License: MIT
Keywords: appimage,linux,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Dynamic: license-file

# Aim AppImage Manager

Aim is a lightweight CLI for installing, launching, updating, and removing AppImages on Linux. It keeps AppImages in one predictable place, adds desktop launcher entries, extracts icons when possible, and cleans everything up when you uninstall.

**Current release:** `0.1.0` alpha.

## Demo

<img width="800" height="482" alt="Aim AppImage Manager demo" src="https://github.com/user-attachments/assets/44eb9d56-5bfc-4567-8bc8-fdffdbd1ad6f" />

Install an AppImage from a URL, then launch it from your app menu with its icon in place.

## Why Aim?

- Install local AppImages or direct AppImage URLs with one command.
- Add apps to your desktop launcher automatically.
- Keep managed AppImages in a consistent user-local folder.
- Update URL-installed apps by redownloading from their saved source.
- Remove installed AppImages, desktop entries, icons, and symlinks cleanly.
- Inspect managed apps without hunting through your filesystem.
- Run without root by default.

## Requirements

- Linux
- Python 3.9+
- `pipx` recommended for installation

Check your Python version with:

```bash
python3 --version
```

## Installation

### Install With pipx

```bash
pipx install git+https://github.com/leonfrancis37/Aim-AppImage-Manager.git
```

After installation:

```bash
aim help
```

### Install pipx

Fedora:

```bash
sudo dnf install pipx
pipx ensurepath
```

Debian/Ubuntu:

```bash
sudo apt install pipx
pipx ensurepath
```

Arch:

```bash
sudo pacman -S python-pipx
pipx ensurepath
```

## Install From Source

```bash
git clone https://github.com/leonfrancis37/Aim-AppImage-Manager.git
cd Aim-AppImage-Manager
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install .
```

Then run:

```bash
aim help
```

## Run From Source

Useful while developing or testing changes:

```bash
git clone https://github.com/leonfrancis37/Aim-AppImage-Manager.git
cd Aim-AppImage-Manager
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 src/main.py help
```

## Quick Start

```bash
aim install ./App.AppImage
aim install https://example.com/App.AppImage --name app
aim run app
aim list --detailed
aim update app
aim uninstall app
```

Aim should be run as your normal user. For `--system`, Aim asks for sudo only when it needs to create or remove a `/usr/local/bin` symlink.

## Commands

| Command | Description |
| --- | --- |
| `aim install <file-or-url>` | Install and register an AppImage. |
| `aim open <file-or-url>` | Run an AppImage once without installing it. |
| `aim run <app>` | Run an installed AppImage by name. |
| `aim update <app> [app ...]` | Redownload URL-installed apps. |
| `aim uninstall <app> [app ...]` | Remove apps and their managed files. |
| `aim list` | Show installed apps. |
| `aim list --detailed` | Show installed apps with paths, source type, and size. |
| `aim info <app>` | Show metadata for one app. |
| `aim path <app>` | Print the managed AppImage path. |
| `aim desktop <app>` | Print the desktop entry path. |
| `aim edit <app>` | Open the desktop entry in your editor. |
| `aim stats` | Show app count and total disk usage. |

## Install Options

| Option | Description |
| --- | --- |
| `--name NAME` | Choose the managed app name. |
| `--replace` | Replace an existing app with the same name. |
| `--no-icon` | Skip icon extraction. |
| `--no-desktop` | Skip desktop entry creation. |
| `--system` | Add a `/usr/local/bin` command symlink. |

Example for a CLI-style AppImage:

```bash
aim install ./tool.AppImage --name tool --system --no-desktop
```

## Updating Apps

Aim can update apps that were installed from a URL because it stores the original source URL:

```bash
aim update app
aim update app another-app
```

Local file installs cannot be updated automatically unless they are reinstalled with `--replace`.

## Where Files Are Stored

Aim stores everything in user-local locations by default:

| What | Location |
| --- | --- |
| AppImages | `~/.local/appimages/` |
| Desktop entries | `~/.local/share/applications/` |
| Extracted icons | `~/.local/share/icons/aim/` |
| Aim app database | `~/.local/share/aim/apps.json` |
| Optional system command symlinks | `/usr/local/bin/` |

The optional `/usr/local/bin/` symlink is only created when using `--system`.

## Distribution

Currently, Aim can be installed with `pipx` from GitHub or from source.

Planned distribution:

- PyPI package for `pipx install aim-appimage-manager`
- Arch User Repository package

## License

Aim is released under the MIT License. See [LICENSE](LICENSE) for details.
