# Managebac-fetch

`managebac-fetch` is a command-line tool that syncs files from the **ManageBac Files** area to your local machine.

It is designed for students who want a reliable local backup of class materials, including nested folders inside class file directories.

## Features

- Proper installable CLI tool
- Works well with `pipx`
- Uses the current ManageBac `/files` interface
- Recursively downloads files inside subfolders
- Sync mode skips files that already exist locally
- Encrypted credential storage on your machine
- Separate configuration command
- Per-class summaries and overall sync summary
- Optional class filtering
- Adjustable parallel download workers
- Configurable absolute sync/download directory with validation
- Cross-platform path handling for Windows, macOS, and Linux

## Installation

### Recommended: `pipx`

Install with:

```bash
pipx install managebac-fetch
```

Once installed, you can run:

```bash
managebac-fetch
```

### Alternative: `pip`

You can also install it with `pip`:

```bash
pip install managebac-fetch
```

## Quick start

### 1. Configure the tool

On first use, run:

```bash
managebac-fetch configure
```

You will be prompted for:

- your ManageBac school code
- your ManageBac username/email
- your ManageBac password
- your default sync/download directory as a full absolute path
- your preferred worker count

The credentials are stored **encrypted** in your user config directory.

### 2. Sync files

After configuration, just run:

```bash
managebac-fetch
```

By default, this behaves the same as:

```bash
managebac-fetch sync
```

It will use your saved configuration and sync all available class files.

## Commands

## `managebac-fetch`

Runs the default sync command using saved configuration.

```bash
managebac-fetch
```

## `managebac-fetch configure`

Prompts for credentials and default settings, validates login, and saves configuration.

```bash
managebac-fetch configure
```

You can also pass values directly:

```bash
managebac-fetch configure --school-code myschool --username you@example.com --output-dir /full/path/to/managebac-sync --workers 4
```

Options:

- `--school-code`
- `--username`
- `--password`
- `--output-dir`
- `--workers`
- `--force`   --> Disable sync mode by default and force redownloads on future runs

## `managebac-fetch sync`

Sync files from ManageBac.

```bash
managebac-fetch sync
```

Useful options:

- `--class-name "Exact Class Name"`   --> Only sync the class whose name exactly matches this value
- `--output-dir path/to/output`   --> Override the configured absolute output directory for this run
- `--workers 4`   --> Override worker count for this run
- `--force`   --> Re-download files even if they already exist locally
- `--quiet-download-progress`   --> Hide per-class file download progress bars
- `--school-code`   --> Override stored school code
- `--username`   --> Override stored username
- `--password`   --> Override stored password (not recommended; prompt is safer)

Examples:

Sync everything using saved settings:

```bash
managebac-fetch sync
```

Sync just one class:

```bash
managebac-fetch sync --class-name "IB DP Economics 2027"
```

Force re-download even if files already exist (disabling sync mode):

```bash
managebac-fetch sync --force
```

Override output directory for a single run:

```bash
managebac-fetch sync --output-dir /full/path/to/managebac-sync
```

## `managebac-fetch config show`

Show a safe summary of saved configuration.

```bash
managebac-fetch config show
```

This shows things like:

- config directory
- whether credentials are saved
- saved school code
- saved username
- output directory
- worker count
- sync mode

The saved output directory should be an absolute full path. The CLI validates it when you save configuration and when you provide an override during sync.

It does **not** print your password.

## `managebac-fetch config clear`

Remove saved config and encrypted credentials.

```bash
managebac-fetch config clear
```

## How sync mode works

Sync mode is enabled by default.

That means:

- if a file already exists locally, it is skipped
- only missing files are downloaded

To disable this behavior and force re-downloads:

```bash
managebac-fetch sync --force
```

## Credential storage

`managebac-fetch` stores credentials in your user config directory and encrypts them before writing them to disk.

### Important note

This protects credentials **at rest** against casual disclosure, but it is not a full enterprise-grade secret management system. The encryption key is stored on the same machine, so a determined local attacker with access to your account may still be able to recover the credentials.

That said, it is still far better than storing passwords in plaintext in a script, shell history, or repository.

## Where configuration is stored

On Windows, configuration is typically stored under:

```text
%APPDATA%\managebac-fetch
```

On Linux/macOS, configuration is typically stored under:

```text
~/.config/managebac-fetch
```

The sync/download destination itself is also part of the saved configuration. It should be provided as a full absolute path using the conventions of your operating system, for example:

Windows:
```text
C:\Users\you\Downloads\managebac-sync
```

macOS/Linux:
```text
/Users/you/Downloads/managebac-sync
```

Paths are normalized and validated by the application so sync behavior works correctly across supported operating systems.

## Output behavior

The CLI shows:

- a clear sync header
- one progress bar for classes
- per-class summaries
- optional per-file download progress bars
- a final summary with:
  - files found
  - downloaded
  - skipped
  - failed

## Supported Python versions

- Python 3.10+
- Python 3.11
- Python 3.12
- Python 3.13

## Contributing

Contributions are welcome! If you have ideas for improvements, bug fixes, or new features, please open an issue or submit a pull request on [GitHub](https://github.com/sukarth/managebac-fetch/issues).

## Development

Clone the repository:

```bash
git clone https://github.com/sukarth/managebac-fetch.git
cd managebac-fetch
```

Install dependencies:

```bash
python -m pip install -r requirements.txt
```

Install in editable mode:

```bash
python -m pip install -e .
```

Run the CLI locally:

```bash
python -m managebac_fetch
```

Or:

```bash
managebac-fetch
```

## Type checking and linting

This project includes configuration for static analysis and packaging.

Examples:

```bash
pyright
ruff check .
python -m build
```

## Notes and limitations

- This tool is built around the current ManageBac `/files` interface.
- It intentionally parses only `.row.file` elements.
- If ManageBac changes their frontend structure significantly, parsing may need to be updated.
- Some classes may genuinely have no visible files in the Files tab.
- Access is limited to files your account can view.

## Repository

- GitHub Repository: https://github.com/sukarth/managebac-fetch

## License

This project is licensed under the MIT License. See `LICENSE.md`.

## Credits

This This project is based on the original [managebac-file-scraper](https://github.com/yutotakano/managebac-file-scraper) by [Yuto Takano](https://github.com/yutotakano/managebac-file-scraper).

This version modernizes it into a complete CLI application with:
- updated scraping logic for the current ManageBac interface
- encrypted saved configuration
- sync support
- recursive subfolder handling
- improved UX and documentation

---

Made with ❤️ by [Sukarth Acharya](https://github.com/sukarth)