Metadata-Version: 2.3
Name: flagonfly
Version: 0.0.3
Summary: The ultimate CTF tool. Designed to combat the staggering lack of cross-platform CTF tools. Named after the ultimate hunter, the dragonfly.
Author: aidnem
Author-email: aidnem <aidnem@noreply.codeberg.org>
Requires-Dist: bitstring>=4.4.0
Requires-Dist: click>=8.4.1
Requires-Dist: ttkbootstrap>=1.20.3
Requires-Python: >=3.13
Project-URL: Repository, https://codeberg.org/aidnem/flagonfly
Project-URL: Issues, https://codeberg.org/aidnem/flagonfly/issues
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

### From PyPI

flagonfly is published to [PyPI](https://pypi.org/project/flagonfly/).

To install it, use a package manager like `uv` or `pip`.

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`:

```sh
uv tool install flagonfly
```

OR

```sh
pipx install flagonfly
```

OR (if you don't mind installing dependencies into your global python environment)

```sh
pip install flagonfly
```

### Local Copy

flagonfly can also be installed by cloning the repo and install it locally using 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 project 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 prepend 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 leverages Codeberg's hosted woodpecker instance for continuous integration: 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 created on Codeerg.
