# Command - AddressBook

Generate an address book file and set of private keys for a FoxMQ session.

Usage: `foxmq address-book <COMMAND>`

### Subcommands

| Command      | Description                                                             | Quick-link                           |
| ------------ | ----------------------------------------------------------------------- | ------------------------------------ |
| `from-list`  | Generate the address book from a list of predetermined socket addresses | [#from-list](#from-list "mention")   |
| `from-range` | Generate the address book from a base IP address and a range of ports   | [#from-range](#from-range "mention") |

### `from-list`

Generate the address book from a list of predetermined UDP socket addresses

These socket addresses correspond to the `--cluster-addr` of each node, or a socket address that connects to it if using `0.0.0.0`.

An error will be returned if the same address is listed more than once.

Usage: `foxmq address-book from-list [OPTIONS] <SOCKET_ADDRESSES>...`

#### Arguments

* `SOCKET_ADDRESSES...`\
  The list of UDP socket addresses (IP:port) to include in the address book.\
  \
  An error will be returned if the same address is listed more than once.

#### Options

* `--log`, `-l`\
  Set the format of log output.
  * Default: `full`
  * Options: `full`, `compact`, `pretty`, `json`
    * `json` is structured and is intended for usage by tools that process structured logs in production environments, and is not optimized for human readability.
* `--output-dir`, `-O`\
  The path to write the address book and secret key files to.\
  \
  If any parent directories in the path do not already exist, they will be created.\
  \
  An error will be returned if the directory already contains an `address-book.toml` or any conflicting `key_*.pem` \
  \
  Pass `-f`/`--force` to overwrite any existing files.
  * Default: `foxmq.d/`
* `--force`/`-f`\
  If any file generated by the command already exists, overwrite it instead of emitting an error.<br>

#### Example

Note: This Example uses IP Addresses from the TEST-NET-1 range, and they're reserved for documentation purposes.

```bash
foxmq address-book from-list \
    -O "foxmq.d/" \
     "192.0.2.0:19793" \
     "192.0.2.1:19793"
```

### `from-range`

Generate the address book from a base IP address and a range of UDP ports.

These socket addresses correspond to the `--cluster-addr` of each node, or a socket address that connects to it if using `0.0.0.0`.

The total number of addresses generated will be `PORT_END - PORT_START + 1` (because the range is inclusive).\
\
Usage: `foxmq address-book from-list [OPTIONS] <BASE_ADDRESS> <PORT_START> <PORT_END>`

#### Arguments

* `BASE_ADDRESS`\
  The base IP address which will be affixed with ports in the given range
* `PORT_START`\
  The start of the UDP port range (inclusive)
* `PORT_END`\
  The end of the UDP port range (inclusive)

#### Options

* `--log`, `-l`\
  Set the format of log output.
  * Default: `full`
  * Options: `full`, `compact`, `pretty`, `json`
    * `json` is structured and is intended for usage by tools that process structured logs in production environments, and is not optimized for human readability.
* `--output-dir`, `-O`\
  The path to write the address book and secret key files to.\
  \
  If any parent directories in the path do not already exist, they will be created.\
  \
  An error will be returned if the directory already contains an `address-book.toml` or any conflicting `key_*.pem` \
  \
  Pass `-f`/`--force` to overwrite any exiting files.
  * Default: `foxmq.d/`
* `--force`/`-f`\
  If any file generated by the command already exists, overwrite it instead of emitting an error.

#### Example

```bash
foxmq address-book from-range \
    -O "foxmq.d/" \
     "127.0.0.1" \
      19793 \
      19794
```