@kabeep/forex-cli

forex-cli

English | 简体中文

📖 Introduction

A Node.js Library to convert foreign exchange in terminal.

⚙️ Installation

npm install --global @kabeep/forex-cli

yarn add --global @kabeep/forex-cli

pnpm add --global @kabeep/forex-cli

🚀 Usage

forex -h

Or use the abbreviation.

fx -h

forex <command> [options]

Commands:
  forex convert [amount]  Convert currency amounts                           [default] [aliases: to]
  forex currency [code]   Get available currency codes and names             [aliases: cur, ccy, cy]
  forex list              Print list of available currencies                           [aliases: ls]
  forex completion        generate completion script

Options:
  -d, --date       The date for the conversion rate, or "latest" for the most recent
                                                                        [string] [default: "latest"]
      --timeout    Request timeout (milliseconds)                          [number] [default: 10000]
  -c, --clipboard  Write (copy) the result to the clipboard               [boolean] [default: false]
  -T, --translate  Translate occurrences of currency or region names      [boolean] [default: false]
  -V, --verbose    Output verbose messages on internal operations         [boolean] [default: false]
  -f, --from       The base currency code or locale code                  [string] [default: "auto"]
  -t, --to         The destination currency code or locale code           [string] [default: "auto"]
  -h, --help       Show help                                                               [boolean]
  -v, --version    Show version number                                                     [boolean]

Examples:
  forex list -t US -d 2024-12-01         Use the exchange rate for the specified date
  forex convert -t US -d "Dec 01, 2024"  Use the exchange rate for the specified date
  -------
  forex convert -t US --timeout 30000    Set request timeout
  forex currency -T -t US                Print the translated currency name or region name
                                                    according to the operating system locale
  forex 1000 -f USD -t EUR               Convert 1000 USD to Euros
  -------
  forex -t USD                           Currency codes using ISO 4217
  forex -t US                            Use locale codes from ISO 3166-1
  forex -t America                       Use country or region name
  -------
  forex --from USD --to EUR              Specify base and target currencies
  forex --from USD                       Specify one of the currencies and automatically f
                                                   ill in the other currency through the OS's locale
  forex --to USD                         Specify one of the currencies and automatically f
                                                   ill in the other currency through the OS's locale

Quick Start

Convert 1000 Euros to your currency (obtained based on OS's locale).

forex 1000 --from EUR

✔ Get the list of available currencies on latest 381ms
✔ Get the currency exchange rate between EUR and USD on latest 120ms
✨ 1,000.00 Euro (EUR) ≈ 1,050.60 US Dollar (USD)

🔩 Command

Command	Aliases	Default	Parameter	Description
convert	to	true	amount	Convert currency amounts
currency	cur / ccy / cy	false	currency code / country or region code /country or region name	Get available currency codes and names
list	ls	false	-	Print list of available currencies
completion	-	false	-	Generate completion script
help	-	false	-	Show help

Common Options:

forex list --date "Dec 01, 2024" --timeout 10000 --translate

Or use the abbreviation.

fx list -d "Dec 01, 2024" --timeout 10000 -TVc

Option	Type	Optional	Default	Description
--date / -d	string	true	"latest"	The date for the conversion rate, or "latest" for the most recent
--timeout	number	true	10_000	Request timeout (milliseconds)
--clipboard / -c	boolean	true	false	Write (copy) the result to the clipboard
--translate / -T	boolean	true	false	Translate occurrences of currency or region names
--verbose / -V	boolean	true	false	Output verbose messages on internal operations
--version / -v	boolean	true	false	Show version number
--help / -h	boolean	true	false	Show help

$ CONVERT (Default)

Convert currency amounts.

Supported amount formats:

• Basic 10000
• Digit Formatting 10_000
• Scientific Notation 1.23e3
• Statistical Formatting 10,000
• Financial Abbreviations 1.1b1m1k1.01

forex convert -h

forex convert [amount]

Convert currency amounts

Options:
  -d, --date       The date for the conversion rate, or "latest" for the most recent
                                                                        [string] [default: "latest"]
      --timeout    Request timeout (milliseconds)                          [number] [default: 10000]
  -c, --clipboard  Write (copy) the result to the clipboard               [boolean] [default: false]
  -T, --translate  Translate occurrences of currency or region names      [boolean] [default: false]
  -V, --verbose    Output verbose messages on internal operations         [boolean] [default: false]
  -f, --from       The base currency code or locale code                  [string] [default: "auto"]
  -t, --to         The destination currency code or locale code           [string] [default: "auto"]
  -h, --help       Show help                                                               [boolean]
  -v, --version    Show version number                                                     [boolean]

Examples:
  forex 1000 -f USD -t EUR   Convert 1000 USD to Euros
  -------
  forex -t USD               Currency codes using ISO 4217
  forex -t US                Use locale codes from ISO 3166-1
  forex -t America           Use country or region name
  -------
  forex --from USD --to EUR  Specify base and target currencies
  forex --from USD           Specify one of the currencies and automatically fill in the o
                                       ther currency through the OS's locale
  forex --to USD             Specify one of the currencies and automatically fill in the o
                                       ther currency through the OS's locale

• Convert 1000 USD to Euros.

  forex convert 1000 --from USD --to EUR
  

  ✔ Get the list of available currencies on latest 369ms
  ✔ Get the currency exchange rate between USD and EUR on latest 119ms
  ✨ 1,000.00 US Dollar (USD) ≈ 951.83 Euro (EUR)
  

• Convert your 1000 quantity currency to Euros (acquired based on OS's locale).

  forex convert 1000 --to EUR
  

  ✔ Get the list of available currencies on latest 369ms
  ✔ Get the currency exchange rate between USD and EUR on latest 119ms
  ✨ 1,000.00 US Dollar (USD) ≈ 951.83 Euro (EUR)
  

• Convert 1000 Euros to your currency (obtained based on OS's locale).

  forex convert 1000 --from EUR
  

  ✔ Get the list of available currencies on latest 369ms
  ✔ Get the currency exchange rate between EUR and USD on latest 119ms
  ✨ 1,000.00 Euro (EUR) ≈ 1,050.60 US Dollar (USD)
  

Option	Type	Optional	Default	Description
--from / -f	string	true	"auto"	The base currency code or locale code
--to / -t	string	true	"auto"	The destination currency code or locale code

$ CURRENCY

Get available currency codes and names.

forex currency [code]

Get available currency codes and names

Options:
  -d, --date       The date for the conversion rate, or "latest" for the most recent
                                                                        [string] [default: "latest"]
      --timeout    Request timeout (milliseconds)                          [number] [default: 10000]
  -c, --clipboard  Write (copy) the result to the clipboard               [boolean] [default: false]
  -T, --translate  Translate occurrences of currency or region names      [boolean] [default: false]
  -V, --verbose    Output verbose messages on internal operations         [boolean] [default: false]
  -h, --help       Show help                                                               [boolean]
  -v, --version    Show version number                                                     [boolean]

Examples:
  forex cy US       Obtained via ISO-3166-1-alpha-2 region code
  forex cy USD      Obtained via ISO 4217 currency code
  forex cy America  Get by country or region name

• Obtained via ISO-3166-1-alpha-2 region code.

  forex currency US
  

  ✔ Get the list of available currencies on latest 369ms
  ✨ US Dollar (USD)
  

• Obtained via ISO 4217 currency code.

  forex currency USD
  

  ✔ Get the list of available currencies on latest 369ms
  ✨ US Dollar (USD)
  

• Get by country or region name.

  forex currency America
  

  ✔ Get the list of available currencies on latest 369ms
  ✨ US Dollar (USD)
  

$ LIST

Print list of available currencies.

forex list -h

forex list

Print list of available currencies

Options:
  -d, --date       The date for the conversion rate, or "latest" for the most recent
                                                                        [string] [default: "latest"]
      --timeout    Request timeout (milliseconds)                          [number] [default: 10000]
  -c, --clipboard  Write (copy) the result to the clipboard               [boolean] [default: false]
  -T, --translate  Translate occurrences of currency or region names      [boolean] [default: false]
  -V, --verbose    Output verbose messages on internal operations         [boolean] [default: false]
  -p, --pretty     Pretty output format                                   [boolean] [default: false]
  -h, --help       Show help                                                               [boolean]
  -v, --version    Show version number                                                     [boolean]

Examples:
  forex ls     Shows the latest list of available currencies
  forex ls -p  Use unicode table to prettier printed content

Option	Type	Optional	Default	Description
--pretty / -p	boolean	true	false	Pretty output format

• Shows the latest list of available currencies.

  forex list
  

  Bitcoin (BTC)
  Chinese Yuan Renminbi (CNY)
  Ethereum (ETH)
  Euro (EUR)
  Japanese Yen (JPY)
  Hong Kong Dollar (HKD)
  Singapore Dollar (SGD)
  US Dollar (USD)
  Tether (USDT)
  Gold Ounce (XAU)
  ...
  

• Use unicode table to prettier printed content.

  forex list --pretty
  

  ┌──────┬────────────────────────────────┬──────────────────────────────────────────┐
  │CODE  │NAME                            │TRANSLATION                               │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │BTC   │Bitcoin                         │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │CNY   │Chinese Yuan Renminbi           │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │ETH   │Ethereum                        │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │EUR   │Euro                            │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │JPY   │Japanese Yen                    │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │HKD   │Hong Kong Dollar                │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │SGD   │Singapore Dollar                │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │USD   │US Dollar                       │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │USDT  │Tether                          │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │XAU   │Gold Ounce                      │ -                                        │
  ├──────┼────────────────────────────────┼──────────────────────────────────────────┤
  │...   │...                             │...                                       │
  └──────┴────────────────────────────────┴──────────────────────────────────────────┘
  

$ COMPLETION

Generate completion script.

forex completion -h

###-begin-forex-completions-###
#
# yargs command completion script
#
# Installation: forex completion >> ~/.bashrc
#    or forex completion >> ~/.bash_profile on OSX.
#
_forex_yargs_completions()
{
    local cur_word args type_list

    cur_word="${COMP_WORDS[COMP_CWORD]}"
    args=("${COMP_WORDS[@]}")

    # ask yargs to generate completions.
    type_list=$(forex --get-yargs-completions "${args[@]}")

    COMPREPLY=( $(compgen -W "${type_list}" -- ${cur_word}) )

    # if no match was found, fall back to filename completion
    if [ ${#COMPREPLY[@]} -eq 0 ]; then
      COMPREPLY=()
    fi

    return 0
}
complete -o bashdefault -o default -F _forex_yargs_completions forex
###-end-forex-completions-###

$ HELP

Show help.

forex help

• Show convert help.

  forex convert help
  

• Show currency help.

  forex currency help
  

• Show list help.

  forex list help
  

🌐 i18n

Language Name	Native Name	ISO-639-1	ISO-3166-1 (Alpha-2)	Locale File
English	-	en	US	en-US.ts
Chinese Simplified	简体中文	zh	CN	zh-CN.ts

🔗 Related

• forex - 💱 A JavaScript foreign exchange library via fawazahmed0's API.

🤝 Contribution

Contributions via Pull Requests or Issues are welcome.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.