dfi-docs/markdown/How-do-I-use-it.md

[//]: # (docker-finance | modern accounting for the power-user)
[//]: # ()
[//]: # (Copyright [C] 2021-2025 Aaron Fiore [Founder, Evergreen Crypto LLC])
[//]: # ()
[//]: # (This program is free software: you can redistribute it and/or modify)
[//]: # (it under the terms of the GNU General Public License as published by)
[//]: # (the Free Software Foundation, either version 3 of the License, or)
[//]: # ([at your option] any later version.)
[//]: # ()
[//]: # (This program is distributed in the hope that it will be useful,)
[//]: # (but WITHOUT ANY WARRANTY; without even the implied warranty of)
[//]: # (MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the)
[//]: # (GNU General Public License for more details.)
[//]: # ()
[//]: # (You should have received a copy of the GNU General Public License)
[//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)

# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")

- **[How do I use it?](#how-do-i-use-it)**
  * [Mostly-Unified CLI](#mostly-unified-cli)
  * [Flow Layout](#flow-layout)
  * [Caveats & Oddities](#caveats--oddities)

## How do I use it?

### Mostly-Unified CLI

You'll only need the single alias `dfi` when using docker-finance on your client (host) and/or within your container.

However, this alias can be broken down into the following:

  1. The client script which handles the client-side (host) system: `docker.bash` (alias `dfi`)
  2. The container script which handles the container-side system: `finance.bash` (alias `dfi`)

These two scripts can be rationalized by the following format:

    <script> <super/sub> <command> [args]

For example, these [Screenshots](What-does-it-do.md#screenshots) describe a setup with mockup data where the client (host) user named `business`, along with container `$DOCKER_FINANCE_USER` named `business`, engage in client/container activity. The container profile named `testprofile` and its subprofile named `testuser` can be described as `<super/sub>` portion of the format (`testprofile/testuser`).

It should be noted that, for your convenience:
  - command arguments [args] can be arranged in any order
  - commandline completion is available for all `dfi <super/sub> command [args]` (save your fingers and tab away!)
    - For client (host), an image must first be built for completion to be available

---

#### Client (Host) Command Format

The client (host) command format consists of:

    docker.bash <platform/username:tag> <command> [args]

Where:

  - `docker.bash` is located in `${DOCKER_FINANCE_CLIENT_REPO}/client`
  - `<platform/username:tag>`
    - `platform` is the image platform (archlinux, ubuntu)
    - `username` is the client (host) username with read/write permissions to the container (see [Configuration Files](How-do-I-get-started.md#configuration-files))
    - `tag` is a custom tag you can use to delineate any number of images that you wish you create (`latest`, `dev`, etc.)
  - `<command>` is the command to pass to `docker.bash`
  - `[args]` are the (optional) arguments to pass to `<command>`

If the [Installation](How-do-I-get-started.md#installation) was successful, `docker.bash` is aliased to `docker-finance` and `dfi` (either can be used).

For a complete list of commands and usage help (`<platform/user:tag>` *not* required):

```bash
dfi help
```

To view the help usage of a specific command, for example; the `edit` command (`<platform/user:tag>` *is* required):

```bash
dfi archlinux/${USER}:default edit help
```

---

#### Container Command Format

The container command format consists of:

    finance.bash <profile/subprofile> <command> [args]

Where:

  - `finance.bash` is located in `${DOCKER_FINANCE_CLIENT_REPO}/container`
  - `<profile/subprofile>`
    - `profile` is the profile, as defined during [Environment Generation](How-do-I-get-started.md#environment-generation)
    - `subprofile` is the subprofile (user), as defined during [Environment Generation](How-do-I-get-started.md#environment-generation)
  - `<command>` is the command to pass to `finance.bash`
  - `[args]` are the (optional) arguments to pass to `<command>`

By default, `finance.bash` is aliased to `finance` and `dfi` (either can be used).

For a complete list of commands (`<profile/subprofile>` *not* required):

```bash
dfi help
```

To view the help usage of a specific command, for example; the `fetch` command (`<profile/subprofile>` *is* required):

Assuming `<profile/subprofile>` is `testprofile/testuser`:

```bash
dfi testprofile/testuser fetch help
```

Or, use a subprofile alias, as described in [Subscript](How-do-I-get-started.md#subscript):

```bash
testuser_fetch help
```

### Flow Layout

A primary read through of [hledger](https://hledger.org) and [hledger-flow](https://github.com/apauley/hledger-flow/blob/master/README.org) documentation should bring you up to speed on most of the essentials.

As for docker-finance specifics, you can create a *test profile* during [Environment Generation](How-do-I-get-started.md#environment-generation) to see what your flow's layout should look like.
> Note: be sure to select 'y' when asked if this will be a development profile, and then go on to create account(s).

Once inside the container, assuming you created a profile named `testprofile` and subprofile named `testuser`, issue the following commands:

```bash
finance testprofile/testuser fetch all=price api=mobula year=all && finance testprofile/testuser import year=2018
```
> Note: for this *test profile* with developer mockups, you **MUST** import from `2018` as there are accounts that begin from that year

After experimenting with a *test profile*, you can re-run `gen` again to create a regular profile.

#### Profiles

All profiles/subprofiles are installed into the parent directory `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles`.

Peeking inside `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile`, you'll see the following:

- `all-years.journal` and `directives.journal`
  - These top-level journals are generated by `hledger-flow`. Ignore these and use the container `edit` command for all journal editing.

- `docker-finance.d`
  - Location of all docker-finance configuration files (see `edit help` for details).

- `import`
  - Location of all CSV data and *real* journals. This is where you'll place CSV files and custom account/subaccount changes (see `edit help` for details).

- `prices`
  - Location of all market price data, by year, as acquired by `fetch price` (see `fetch help` for details).

- `reports`
  - Location of all generated reports, by year, as generated by `reports` (see `reports help` for details).

- `taxes`
  - Location of all generated taxes, by year, as generated by `taxes` (see `taxes help` for details).

Note:

  - For manual CSV downloads, place you CSV file into your `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile/import/subprofile/account/subaccount/1-in/year` directory (replacing `year` with the year of data that the file/data represents). See `import help` for details.
  - When you want to edit custom settings for an account or a subaccount, use the container `edit` command. See container's `edit help` for details.

#### Times

All `times` related files will reside in `${DOCKER_FINANCE_CONTAINER_FLOW}/times` (this includes the timewarrior database).

See the container `times help` command for details.

### Caveats & Oddities

#### Flow Layout

Your `finance-flow` directory will contain a symlink called `src` which links to code that processes your data. **Do not delete this symlink**.

##### *Prices*

Before you try to infer market prices, be sure to fetch prices *before* you do your first import (or first import of the year). If you do not fetch, the prices journal will **not** be included within the import and, if you have a previous year of prices, **you will unwittingly infer against that previous year instead of your expected year!**

##### *Accounts: Trezor*

In the "Trezor Suite" app, change your wallet name to your subaccount(s). For example, to delineate between your Trezor One from several Trezor T devices, and to delineate between their separate wallets *within* every device, follow these steps:

Example, using your #2 Trezor T device and one of its BTC "storage" wallets:

   1. Change wallet name in app to `t-2:storage-1` as it's your Trezor T device #2, 1st bitcoin wallet named `storage-1` (versus your 2nd bitcoin wallet named `storage-2`, etc.)
   2. Export the CSV file to the appropriate directory. It will be in the format of `t_2_storage_1_20230629T230013.csv` (timestamp will be different)
   3. Rename the file to `t-2:storage-1_BTC.csv` (be sure to append the currency ticker to the file. So, `_BTC` if bitcoin or `_LTC` if litecoin, etc).

> Note: see Trezor `mockup` data within the docker-finance repository for a working example.

docker-finance relies on `Amount unit` within the file for the actual symbol/currency so, this file naming convention serves at least two purposes:

  1. This allows you to maintain device continuity by reusing wallet names for different currencies.
  2. This allows you to export, in the future, to the correct file from the associated hardware wallet because each hardware wallet exports its own unique CSV.

#### Taxes

- If you have a wallets designated for `SPEND`ing/`GIFT`ing or `INCOME`, you can use custom rules to mark all outgoing/incoming transactions as such (ex., using tags `taxed_as:SPEND`/`taxed_as:GIFT`/`taxed_as:INCOME`/etc.). See implementation for details.
- **WARNING**: *all* `GIFTIN` cost-basis must be manually entered from the corresponding `GIFT` results/calculations (as gifted from another).
  - For blockchain-related transactions, you can easily add cost-basis of a gift received (`GIFTIN`) by TXID in your custom rules
    - Example: despite Electrum providing `fiat_value`, you'll need to manually enter in your custom rules the correct `GIFT` value (if divergent)

[//]: # (vim: sw=2 sts=2 si ai et)