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

• How do I use it?
  • Mostly-Unified CLI
  • Flow Layout
  • 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 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)
  • 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 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):

dfi help

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

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
  • subprofile is the subprofile (user), as defined during 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):

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:

dfi testprofile/testuser fetch help

Or, use a subprofile alias, as described in Subscript:

testuser_fetch help

Flow Layout

A primary read through of hledger and hledger-flow 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 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:

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 SPENDing/GIFTing 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)