# 2. The `bitmath` command-line Tool

`bitmath` includes a CLI utility for easily converting units in a shell. For reference, there is also a manpage included, bitmath (1).

## 2.1. Synopsis

    bitmath [--from-stdin] [-f IN_UNIT] [-t OUT_UNIT] VALUE ...

## 2.2. Options

-f <IN_UNIT>

  Specify the input unit to convert from. Defaults to `bitmath.Byte`.

-t <OUT_UNIT>

  Specify the output unit to convert to. Defaults to the best human-readable prefix unit.

--from-stdin

  Reads number from stdin rather than as a CLI argument.

VALUE

  The value to convert.

## 2.3. Examples

Convert `1024` into the best human-readable unit. Without specifying any `from` or `to` values this examples defaults to treating the input value as a `bitmath.Byte`:

    $ bitmath 1024
    1.0 KiB

Convert 1024 KiB into kBs:

    $ bitmath -f KiB -t kb 1024
    8388.608 kb

Convert 1073741824 bytes into the best human-readable unit:

    $ bitmath -f Byte 1073741824
    1.0 GiB

Use the stat command to print the size of `bitmath/__init__.py` in bytes, pipe the output into the bitmath command, and print the result in MBs:

    $ stat -c '%s' bitmath/__init__.py | bitmath --from-stdin -t MB
    0.038374 MB

Convert several values at once from Bytes (the default behavior) into MBs:

    $ bitmath -t MB 1234567 9876543 1337 42
    1.234567 MB
    9.876543 MB
    0.001337 MB
    4.2e-05 MB