Metadata-Version: 2.3
Name: flagonfly
Version: 0.0.1
Summary: Add your description here
Author: aidnem
Author-email: aidnem <aidnem@noreply.codeberg.org>
Requires-Dist: bitstring>=4.4.0
Requires-Dist: click>=8.4.1
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# flagonfly

The ultimate CTF tool. Designed to combat the staggering lack of cross-platform CTF tools. Named after the ultimate hunter, the dragonfly. 

## Installation

For now, flagonfly is not published to any package repositories. To install it, use `pip` or `uv`:

1. First, clone the repository somewhere convenient. Change directory into the project:

```sh
git clone https://codeberg.org/aidnem/flagonfly.git
cd flagonfly
```

2. Install the package using your package manager of choice.

It's preferable to use a package manager that will install the project in its own isolated environment, such as `uv tool install` or `pipx install`.

Install the project in editable mode (use the `-e` flag) so that it can be updated by running `git pull` at a later time:

```sh
uv tool install -e .
```

Alternatively, use pipx:

```sh
pipx install -e .
```

Finally, if you prefer pip, you can use that instead. Keep in mind that this will install the dependencies to your global pip environment:

```sh
pip install -e .
```

Installing using any of these 3 methods will add 3 executables to your python script path:

- `flagonfly` - The flagonfly CLI. This is how all CLI tools can be used.
- `flf` - A convenient alias for `flagonfly`. Because the command is intended to be deeply composed (e.g. `cat data | flf encode binary | rev | flf decode binary`), a shorter alias is useful in saving time composing commands.
- `flagonfly-gui` - Launches the flagonfly GUI, a tkinter app that is intended to provide some of the functionality of the flagonfly library in a graphical form.

## Core Library

The flagonfly project is separated into core, UI, and CLI projects so that the central functionality of the can be used from other projects. Please note that, during early development, doc comments will likely be sparse. To use the functionality of flagonfly in other projects, look into importing necessary functions and packages from `flagonfly.core`.

## CLI: Subcommands

### Help

Flagonfly contains detailed help messages for commands and their parameters wherever possible. Use the `--help` flag on any command to see detailed descriptions of the arguments.

This is important because this README will likely be updated less often and less thoroughly than the help messages themselves.

### Encode/decode

Use `flagonfly encode` or `flagonfly decode` followed by a format to convert data to different formats.

For example, `echo "Hello, world!" | flagonfly encode binary` will encode the ASCII text into binary and output it as a string of "1"s and "0"s. The `decode` command does the reverse.

If an encoding isn't specified when decoding, flagonfly will attempt to guess at what encoding was used. It does this by attempting to decode using various encodings in order until one succeeds. This is not foolproof; if you data was encoded in a larger format but using only certain digits (e.g. data encoded as hex that only uses 1s and 0s), it will decode incorrectly. However, it's good enough as a first try for decoding data quickly.

#### Words and separators

By default, the output of `encode` is divided into words, separated by a separator string. There are sensible defaults for all data types, and the separator/word length parameters are ignored when encoding to base64/32/16.

To change the separator, pass a string to the `-s`/`--separator` option. To remove the separator, pass an empty string: `flagonfly encode -s "" ...`.

To change the word size, use the `-w` or `--word-length` option.

#### Prefixes
The `-p`/`--prefix` option can be used to append a prefix (e.g. `0b` for binary data). When using no separator, this prefix is appended to the beginning of the output. When using a separator between words, it will be appended to the beginning of each word.

There is no prefix for base64/32/16 data.

## CI Usage

The flagonfly project will hopefully leverage Codeberg's hosted woodpecker instance for continuous integration. Its needs are fairly bare-bones: running unit tests on all PRs to main, and running an automatic publish workflow to publish the project to PyPI automatically whenever a new release is tagged. The processing, memory, and storage requirements of these workflows should be minimal, as the project will hopefully remain quite small.
