Metadata-Version: 2.4
Name: lufah
Version: 0.9.1
Summary: Command line utility for controlling foldingathome version 8
Project-URL: Homepage, https://github.com/kbernhagen/lufah
Project-URL: Changelog, https://github.com/kbernhagen/lufah/blob/main/CHANGELOG.md
Author-email: Kevin Bernhagen <kbernhagen.github@gmail.com>
License: MIT License
        
        Copyright (c) 2024-2025 Kevin Bernhagen
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: fah,folding-at-home,folding@home,foldingathome
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8.1
Requires-Dist: shellingham
Requires-Dist: typer-slim
Requires-Dist: websockets>=13.0.1
Description-Content-Type: text/markdown

# lufah

Little Utility for FAH v8

A python command line utility for macOS, Linux, Windows

## Requirements

- python 3.8 or later

## Install from PyPI

Install in isolated user environment (preferred):
```
pip install pipx
pipx install lufah
```

Or
```
pip install lufah
```

## Uninstall

```
pip install pipx
pipx uninstall lufah
```

Or
```
pip uninstall lufah
```

## Install from source

macOS / Linux / Windows
```
git clone https://github.com/kbernhagen/lufah.git
cd lufah
make install-user
```

## Uninstall from source

```
git clone https://github.com/kbernhagen/lufah.git
cd lufah
make uninstall-user
```

## Usage

Note that lufah uses unencrypted, direct websocket connections.
This is what Web Control uses to connect to the local client.
This has security implications if you enable direct remote access on a client.
See [HOWTO: Allow v8 Client Remote Control](https://foldingforum.org/viewtopic.php?t=39050)

```
lufah -h
```

```
Usage: lufah [OPTIONS] COMMAND [ARGS]...

  Little Utility for FAH v8

Options:
  -a, --address ADDRESS  [host][:port][/group] or
                         [host][:port],[host][:port]... Use "." for localhost.
                         Group name must not be url-encoded, but may need
                         escaping from shell. Can be a comma-separated list of
                         hosts for commands units, info, fold, finish, pause
                         [default: localhost:7396]
  -v, --verbose
  -d, --debug
  --version              Show version and exit.
  --install-completion   Install completion for the current shell.
  --show-completion      Show completion for the current shell, to copy it or
                         customize the installation.
  -h, --help             Show this message and exit.

Commands:
  fold               Start folding in specified group or all groups.
  finish             Finish folding and pause specified group or all groups.
  pause              Pause folding in specified group or all groups.
  unpause            (Deprecated) alias for fold
  wait-until-paused  Run until specified group or all groups are paused.
  config             Get or set config values.
  create-group       Create group if it does not exist.
  dump-all           Dump all paused units in specified group or all groups.
  enable-all-gpus    Enable all unclaimed gpus in specified group.
  state              Show json snapshot of client state.
  status             (Deprecated) alias for state
  get                Show json value at dot-separated key path in client...
  groups             Show json array of resource group names.
  info               Show host and client info.
  log                Show client log.
  top                Show top-like updating units table.
  units              Show table of all units by machine name and group.
  watch              Show incoming messages.
  link-account       Link to account by token.
  unlink-account     Unlink account.
  restart-account    Restart account/node connection.
  start              Start local client service.
  stop               Stop local client service.
```

```
lufah config -h
```

```
Usage: lufah config [OPTIONS] COMMAND [ARGS]...

  Get or set config values.

  Other than for account settings (user, team, passkey, cause), a group must
  be specified if there is more than one group.

  Example: lufah -a / config cpus 0

Options:
  -h, --help  Show this message and exit.

Commands:
  beta        Enable beta work units.
  cause       Set cause preference.
  checkpoint  (Deprecated) Set requested CPU WU checkpoint frequency in
              minutes.
  cpus        Set number of cpus to allocate to resource group.
  cuda        Enable CUDA for WUs in specified group.
  fold-anon   (Deprecated) Fold anonymously.
  hip         Enable HIP for WUs in specified group.
  keep-awake  Prevent system sleep while folding and not on battery.
  key         Set project key for internal beta testing of new projects.
  on-battery  Fold even if on battery.
  on-idle     Only fold while user is idle.
  passkey     Set passkey token for quick return bonus points.
  priority    (Deprecated) Set preferred core task priority.
  team        Set team number.
  user        Set folding user name, "" or 2 to 100 bytes.
```

## Examples

```
lufah units
lufah -a //rg2 finish
lufah -a /mygpu1 config cpus 0
lufah -a host1,host2,host3 units
lufah -a host1,host2,host3 info
```

## Notes

If not given, the default command is "units".

If there are multiple groups, config requires a group name,
except for account settings (user, team, passkey, cause).

For command `lufah -a /groupname config cpus N`, N is not limited to unused cpus across groups.

Group "/" is taken to mean the default group, which is "".

For a group name actually starting with "/", use prefix "//".
Example: `lufah -a somehost//rg1 finish`

An error may not be shown if connection times out.

Commands start and stop are macOS-only.

The `top` command is glitchy on Windows when the window is resized.
Type space to force a redraw.
To use `lufah top` on Windows, you may need to manually install `windows-curses`.

## Example Output

```
lufah -a .,panda.local units
```
```
--------------------------------------------------------------------------------
Project  CPUs  GPUs  Core  Status          Progress  PPD        ETA     Deadline
--------------------------------------------------------------------------------
Panda/                     Run 
12462    4     0     0xa8  Running          97.6%    118,692    6m 28s   3d 7h  
Sanctuary/                 Run 
18806    12    0     0xa9  Running          49.7%    385,809    3h 2m    2d 23h 
Sanctuary/aux              Paused

Total PPD: 504,501
```
