Forecast API is a financial forecasting framework designed to help individuals and businesses model the expected flow of money. That framework can be actively implemented via the forecast Command Line Interface (CLI) program for Debian and Debian-based Linux operating systems. The forecast CLI rapidly produces financial forecasts in accordance with the Forecast API framework.
There are four essential components that that comprise the Forecast API:
forecast CLI: A practical command-line implementation of that specification for Debian-based linux operating systems.Beyond basic book-keeping practices, maintaining an accurate transaction schedule file is essential for individuals and businesses to remain financially informed. The schedule file essentially contains a list of all scheduled future transactions, and can account for cyclical, recurring transactions and singular, non-recurring transactions.
The forecast CLI requires a properly formatted transaction file in order to generate forecast data. By definition, scheduled transactions are those that are slated to occur in the future. As such, their values can be both estimated amounts or exact amounts, depending on whether a specific value is known. To get an idea of the syntax requirements for the schedule file, it can be helpful review an example. The forecast CLI ships with an example template file for this reason, and that template file can be generated by running the following command in the terminal:
forecast template-example
If no additional arguments are specified, the example transaction schedule will be printed to directly to the terminal window. The command below includes a modification that will write the contents to a new file in the Desktop directory:
forecast template-example > ~/Desktop/template-example.json
The contents of the example file are as follows:
{
"forecast_begin_y": 2027,
"forecast_begin_m": 1,
"forecast_begin_d": 1,
"forecast_end_y": 2027,
"forecast_end_m": 12,
"forecast_end_d": 31,
"le_sch": [
{
"alias": "sales",
"description": "Sales revenue",
"value": 25000.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 1,
"interval": 1,
"interval_unit": "month",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "payroll",
"description": "Employee payroll - 10 employees",
"value": -30000.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 15,
"interval": 2,
"interval_unit": "week",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "payroll-tax",
"description": "Employer payroll taxes",
"value": -3000.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 15,
"interval": 2,
"interval_unit": "week",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "rent",
"description": "Office rent",
"value": -5000.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 1,
"interval": 1,
"interval_unit": "month",
"time_sch_end_y": 2027,
"time_sch_end_m": 12,
"time_sch_end_d": 1
},
{
"alias": "utilities",
"description": "Utilities",
"value": -750.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 15,
"interval": 1,
"interval_unit": "month",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "insurance",
"description": "Business insurance",
"value": -1200.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 1,
"interval": 1,
"interval_unit": "month",
"time_sch_end_y": 2027,
"time_sch_end_m": 12,
"time_sch_end_d": 1
},
{
"alias": "supplies",
"description": "Office and operating supplies",
"value": -1000.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 10,
"time_sch_d": 1,
"interval": 1,
"interval_unit": "month",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "software",
"description": "Software subscriptions",
"value": -800.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 1,
"interval": 1,
"interval_unit": "month",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "marketing",
"description": "Marketing and advertising",
"value": -1500.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 10,
"interval": 1,
"interval_unit": "month",
"time_sch_end_y": 2027,
"time_sch_end_m": 12,
"time_sch_end_d": 10
},
{
"alias": "equipment",
"description": "Equipment purchase",
"value": -15000.0,
"method": "manual",
"time_sch_y": 2027,
"time_sch_m": 6,
"time_sch_d": 1,
"interval": 0,
"interval_unit": "month",
"time_sch_end_y": 2027,
"time_sch_end_m": 12,
"time_sch_end_d": 31
},
{
"alias": "loan",
"description": "Business loan payment",
"value": -2500.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 5,
"interval": 1,
"interval_unit": "month",
"time_sch_end_y": 2027,
"time_sch_end_m": 12,
"time_sch_end_d": 5
},
{
"alias": "accounting",
"description": "Accounting services",
"value": -1000.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 1,
"interval": 3,
"interval_unit": "month",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "tax",
"description": "Quarterly estimated tax payment",
"value": -5000.0,
"method": "auto",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 15,
"interval": 3,
"interval_unit": "month",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "uns-sma",
"description": "Weekly small unscheduled transactions",
"value": -500.0,
"method": "manual",
"time_sch_y": 2027,
"time_sch_m": 1,
"time_sch_d": 1,
"interval": 1,
"interval_unit": "week",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
},
{
"alias": "uns-lar",
"description": "Yearly large unscheduled transactions",
"value": -5000.00,
"method": "manual",
"time_sch_y": 2027,
"time_sch_m": 7,
"time_sch_d": 1,
"interval": 1,
"interval_unit": "year",
"time_sch_end_y": 3000,
"time_sch_end_m": 1,
"time_sch_end_d": 1
}
]
}
As you can see in the data, the transaction file is a JSON formatted list of scheduled transactions. It also includes, at the beginning, a forecast start date and a forecast end date.
forecast CLI programThe example transaction schedule file can be modified to account for a specific circumstance. However, for the purposes of this article, a forecast was generated based on the data in the example. A forecast can be generated by running the following command, where TRANSACTION-SCHEDULE-FILE is a placeholder for the path to the actual transaction schedule file:
forecast TRANSACTION-SCHEDULE-FILEIn this specific example, the transaction schedule file is the file ~/Desktop/template-example.json. The following data constitutes the program output from that command:
$ forecast ~/Desktop/template-example.json
FORECAST API / CLI Version 1.0-4
------
(= t_i 2027-01-01)
(= t_f 2027-12-31)
TABLE
------
alias description value method t_sch t_sch_end delta_t interval quant_tra sum_t
sales Sales revenue 25000.00 auto 2027-01-01 3000-01-01 360 30 12 300000.00
rent Office rent -5000.00 auto 2027-01-01 2027-12-01 330 30 11 -55000.00
insurance Business insurance -1200.00 auto 2027-01-01 2027-12-01 330 30 11 -13200.00
software Software subscriptions -800.00 auto 2027-01-01 3000-01-01 360 30 12 -9600.00
accounting Accounting services -1000.00 auto 2027-01-01 3000-01-01 360 90 4 -4000.00
uns-sma Weekly small unscheduled transactions -500.00 manual 2027-01-01 3000-01-01 360 7 52 -26000.00
loan Business loan payment -2500.00 auto 2027-01-05 2027-12-05 330 30 11 -27500.00
marketing Marketing and advertising -1500.00 auto 2027-01-10 2027-12-10 330 30 11 -16500.00
payroll Employee payroll - 10 employees -30000.00 auto 2027-01-15 3000-01-01 346 14 25 -750000.00
payroll-tax Employer payroll taxes -3000.00 auto 2027-01-15 3000-01-01 346 14 25 -75000.00
utilities Utilities -750.00 auto 2027-01-15 3000-01-01 346 30 12 -9000.00
tax Quarterly estimated tax payment -5000.00 auto 2027-01-15 3000-01-01 346 90 4 -20000.00
equipment Equipment purchase -15000.00 manual 2027-06-01 2027-12-31 210 0 1 -15000.00
uns-lar Yearly large unscheduled transactions -5000.00 manual 2027-07-01 3000-01-01 180 365 1 -5000.00
supplies Office and operating supplies -1000.00 auto 2027-10-01 3000-01-01 90 30 3 -3000.00
The total sum of all transactions in the forecast: -728800.0
GAGNON WEB SERVICES
------
© 2026 Christopher Gagnon
Gagnon Web
https://gagnonweb.com
EOR
The forecast program can also produce the forecast data in CSV format when the following command is entered:
forecast -c TRANSACTION-SCHEDULE-FILEThe forecast CLI program computes a summary metric via the Forecast API framework, and that metric is the sum of all transactions in the forecast. The Forecast API framework identifies that metric as a signal indicator for individuals and businesses alike who are attempting to navigate a highly complex financial future.
To purchase a Forecast API license, contact Christopher at gagnon@gagnonweb.com. page.