1. Download Costflow Hub

Choose the program you want to download on the download page.

If you want to run it on a linux server, you can also download using the following command:

curl -L https://self-hosted.costflow.io/download/linux --output costflow-hub-linux
sudo chmod 755 ./costflow-hub-linux

Compatibility test

Run Costflow Hub with the commands in step 6 now. If the program is not crash and displays version info, you're good to go.

2. Get a license

We will send the license to your email once you purchased Costflow Hub on Gumroad.

💡

Your license can be used in any supported operating system, but only one can be running at the same time.

3. Apply a Telegram bot token

Send command /newbot to the @botfather, then reply the bot name and username, that's it.

4. Configure `hub.json`

Create a new file named hub.json in the same directory as the Costflow Hub program.

A sample hub.json file:

{
  "license": "AAAAAAAA-BBBBBBBB-CCCCCCCC-DDDDDDDD",
  "telegram_bot_token": "11111111:AAAAAAABBBBBBBCCCCCCDDDD",
  "authorized_users": {
    "telegram": "leplay"
  },
  "config_path": "",
  "ledger_path": "~/costflow-hub/%YYYY/MM%.bean",
  "proxy": ""
}

💡

Replace license and telegram_bot_token with your own. For security concerns, you must fill your Telegram username into authorized_users.telegram , so only your messages will be accepted and saved to ledger files. config_path is the path of costflow.json . Leave it blank if it is in the same directory as hub.json. ledger_path is the path where ledger files will be saved. Some date variables are supported (YYYY, MM, DD, the whole path needs to be surrounded using % ). For example, %YYYY/MM%.bean means to save all entries by month under the year folder. proxy is designed for connecting Telegram API, HTTP/HTTPS proxies are supported. E.g., https://1.1.1.1:2020。

5. Configure `costflow.json`

costflow.json is the config file of Costflow Syntax. A sample file:

{
  "currency": "USD",
  "mode": "beancount",
  "timezone": "Asia/Hong_Kong",
  "tag": "#costflow",
  "indent": 2,
  "lineLength": 50,
  "insertTime": "metadata",
  "alphavantage": "AAAABBBBCCCC",
  "account": {
    "cloud": "Expenses:Tech:Cloud",
    "eob": "Equity:Opening-Balances",
    "spotify": "Expenses:Entertainment:Spotify",
    "visa": "Liabilities:CreditCard:VISA"
  },
  "formula": {
    "aws": "! @AWS {{ amount }} USD visa > cloud",
    "spotify": "! @Spotify 15.98 USD visa > spotify"
  }
}

You can get more info on Costflow Syntax docs.

6. Run

Once the above steps finished, you can start the program by opening a terminal window and use cd command to the program directory, then run the following command:

Mac OS

./costflow-hub-macos

Windows

# Type command in Terminal app, double-click will not work.
costflow-hub-win.exe

Linux

./costflow-hub-linux

If you want to run Costflow Hub background on a remote server, you can use screen command.

Docs

https://www.costflow.io/docs/

Security Tips

Do not share your Telegram token and bot's username.
You can revoke your Telegram bot's token via @botfather if necessary. If your bot keeps getting messages from other users, you should consider creating a new bot (the username of Telegram bot is not allowed to change at the moment).
Do not share your license.
If you want to run Costflow Hub on a server, you should disable all unnecessary ports on network or firewall settings.

Self-Hosted Costflow Hub Docs