CLI

skforecast-ai

Deterministic forecasting assistant powered by skforecast.

Usage

skforecast-ai [OPTIONS] COMMAND [ARGS]...

Arguments

No arguments available

Options

Name	Description	Required	Default
--version	Show version.	No	-
--install-completion	Install completion for the current shell.	No	-
--show-completion	Show completion for the current shell, to copy it or customize the installation.	No	-

Commands

Name	Description
profile	Profile a dataset and recommend a...
plan	Generate a detailed forecasting plan from...
refine-plan	Refine an existing forecasting plan by...
forecast-code	Generate a complete Python forecasting...
backtest-code	Generate a complete Python backtesting...
forecast	Run end-to-end forecasting and report...
backtest	Run backtesting evaluation and report...
compare	Compare several forecasters and report a...
ask	Ask a forecasting question using an LLM.
check-llm	Check how the LLM configuration resolves...
mcp	Serve the deterministic workflow to MCP...
config	Manage persistent configuration.

Subcommands

profile

Profile a dataset and recommend a forecaster and an estimator.

Usage

skforecast-ai profile [OPTIONS] {data}

Arguments

Name	Description	Required
data	Path or URL to CSV file.	Yes

Options

Name	Description	Required	Default
-t, --target	Target column name(s), comma-separated.	Yes	-
-d, --date-column	Date/timestamp column.	No	-
-s, --series-id-column	Series identifier column.	No	-
--exog-columns	Comma-separated columns to use as exogenous variables, 'none' for none, or 'auto' for every column that is not the target, the date or the series id. The other columns are not used.	No	-
--sep	Separator of the CSV file: ',', ';' or 'tab'. Detected from the file when omitted.	No	-
--decimal	Decimal mark of the CSV file: '.' or ',' (only when the separator is not ','). Detected from the file when omitted.	No	-
--format [table|json]	Output format: table or json.	No	table
-o, --output	Write output to file.	No	-
-q, --quiet	Suppress spinners.	No	False

plan

Generate a detailed forecasting plan from a dataset.

Usage

skforecast-ai plan [OPTIONS][data]

Arguments

Name	Description	Required
data	Path or URL to CSV file.	No

Options

Name	Description	Required	Default
-t, --target	Target column name(s), comma-separated.	No	-
--steps	Forecast horizon (number of steps).	No	-
-d, --date-column	Date/timestamp column.	No	-
-s, --series-id-column	Series identifier column.	No	-
--forecaster	Override forecaster class.	No	-
--estimator	Override estimator class, or the Hugging Face model ID for ForecasterFoundation (e.g. 'google/timesfm-3.0-pytorch').	No	-
--estimator-kwargs	Estimator hyperparameters as JSON string, e.g. '{"n_estimators": 200}'.	No	-
--interval	Prediction interval as two quantiles between 0 and 1, e.g. '0.1,0.9' for an 80% interval.	No	-
--lags	Explicit lags as an int or comma-separated list, e.g. '1,2,3', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--window-features	Explicit window features as JSON array, e.g. '[{"stats": ["mean"], "window_size": 7}]', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--metric	Metric, or comma-separated metrics whose first one is the primary metric; only those are computed. 'auto' selects them from the data again when refining a saved plan.	No	-
--use-exog	Use the exogenous columns: 'true', 'false' (forecast then takes no --exog) or 'auto' for the rule.	No	-
--differentiation	Order of differencing of the target before training (an integer of at least 1), or 'auto' for the rule (no differencing). Machine learning forecasters only.	No	-
--calendar-features	Comma-separated calendar features (e.g. 'month,day_of_week'), 'none' for none, or 'auto' for those selected from the frequency. Machine learning forecasters only.	No	-
--target-transformer	Scaler of the target: 'StandardScaler', 'none', or 'auto' for the rule. Machine learning forecasters only.	No	-
--dropna-from-series	Drop the training rows with missing values: 'true', 'false' or 'auto' for the rule. Machine learning forecasters only.	No	-
--exog-columns	Comma-separated columns to use as exogenous variables, 'none' for none, or 'auto' for every column that is not the target, the date or the series id. The other columns are not used.	No	-
--from-profile	Load profile from JSON file or '-' for stdin.	No	-
--format [table|json]	Output format: table or json.	No	table
-o, --output	Write output to file.	No	-
-q, --quiet	Suppress spinners.	No	False

refine-plan

Refine an existing forecasting plan by overriding specific fields or using LLM guidance.

Usage

skforecast-ai refine-plan [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
--from-plan	Load plan bundle from JSON file or '-' for stdin.	Yes	-
--forecaster	Override forecaster class.	No	-
--estimator	Override estimator class, or the Hugging Face model ID for ForecasterFoundation (e.g. 'google/timesfm-3.0-pytorch').	No	-
--estimator-kwargs	Estimator hyperparameters as JSON string, e.g. '{"n_estimators": 200}'.	No	-
--steps	Override forecast horizon.	No	-
--interval	Override prediction interval as two quantiles between 0 and 1, e.g. '0.1,0.9'.	No	-
--lags	Explicit lags as an int or comma-separated list, e.g. '1,2,3', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--window-features	Explicit window features as JSON array, e.g. '[{"stats": ["mean"], "window_size": 7}]', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--metric	Metric, or comma-separated metrics whose first one is the primary metric; only those are computed. 'auto' selects them from the data again when refining a saved plan.	No	-
--use-exog	Use the exogenous columns: 'true', 'false' (forecast then takes no --exog) or 'auto' for the rule.	No	-
--differentiation	Order of differencing of the target before training (an integer of at least 1), or 'auto' for the rule (no differencing). Machine learning forecasters only.	No	-
--calendar-features	Comma-separated calendar features (e.g. 'month,day_of_week'), 'none' for none, or 'auto' for those selected from the frequency. Machine learning forecasters only.	No	-
--target-transformer	Scaler of the target: 'StandardScaler', 'none', or 'auto' for the rule. Machine learning forecasters only.	No	-
--dropna-from-series	Drop the training rows with missing values: 'true', 'false' or 'auto' for the rule. Machine learning forecasters only.	No	-
--prompt	Domain knowledge in natural language; the LLM proposes lags and window features from it.	No	-
--llm	LLM provider and model, e.g. 'openai:gpt-5.5'.	No	-
--base-url	Custom LLM endpoint: server URL for ollama or an OpenAI-compatible API, AWS region for bedrock.	No	-
--api-key	API key for the LLM provider.	No	-
--format [table|json]	Output format: table or json.	No	table
-o, --output	Write output to file.	No	-
-q, --quiet	Suppress spinners.	No	False

forecast-code

Generate a complete Python forecasting script.

Usage

skforecast-ai forecast-code [OPTIONS][data]

Arguments

Name	Description	Required
data	Path or URL to CSV file.	No

Options

Name	Description	Required	Default
-t, --target	Target column name(s), comma-separated.	No	-
--steps	Forecast horizon (number of steps).	No	-
-d, --date-column	Date/timestamp column.	No	-
-s, --series-id-column	Series identifier column.	No	-
--forecaster	Override forecaster class.	No	-
--estimator	Override estimator class, or the Hugging Face model ID for ForecasterFoundation (e.g. 'google/timesfm-3.0-pytorch').	No	-
--estimator-kwargs	Estimator hyperparameters as JSON string, e.g. '{"n_estimators": 200}'.	No	-
--interval	Prediction interval as two quantiles between 0 and 1, e.g. '0.1,0.9' for an 80% interval.	No	-
--lags	Explicit lags as an int or comma-separated list, e.g. '1,2,3', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--window-features	Explicit window features as JSON array, e.g. '[{"stats": ["mean"], "window_size": 7}]', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--metric	Metric, or comma-separated metrics whose first one is the primary metric; only those are computed. 'auto' selects them from the data again when refining a saved plan.	No	-
--use-exog	Use the exogenous columns: 'true', 'false' (forecast then takes no --exog) or 'auto' for the rule.	No	-
--differentiation	Order of differencing of the target before training (an integer of at least 1), or 'auto' for the rule (no differencing). Machine learning forecasters only.	No	-
--calendar-features	Comma-separated calendar features (e.g. 'month,day_of_week'), 'none' for none, or 'auto' for those selected from the frequency. Machine learning forecasters only.	No	-
--target-transformer	Scaler of the target: 'StandardScaler', 'none', or 'auto' for the rule. Machine learning forecasters only.	No	-
--dropna-from-series	Drop the training rows with missing values: 'true', 'false' or 'auto' for the rule. Machine learning forecasters only.	No	-
--from-plan	Load plan bundle from JSON file or '-' for stdin.	No	-
--format [code|json]	Output format: code or json.	No	code
-o, --output	Write output to file.	No	-
-q, --quiet	Suppress spinners.	No	False

backtest-code

Generate a complete Python backtesting script without executing it.

Usage

skforecast-ai backtest-code [OPTIONS][data]

Arguments

Name	Description	Required
data	Path or URL to CSV file.	No

Options

Name	Description	Required	Default
-t, --target	Target column name(s), comma-separated.	No	-
--steps	Forecast horizon (number of steps).	No	-
-d, --date-column	Date/timestamp column.	No	-
-s, --series-id-column	Series identifier column.	No	-
--forecaster	Override forecaster class.	No	-
--estimator	Override estimator class, or the Hugging Face model ID for ForecasterFoundation (e.g. 'google/timesfm-3.0-pytorch').	No	-
--estimator-kwargs	Estimator hyperparameters as JSON string, e.g. '{"n_estimators": 200}'.	No	-
--interval	Prediction interval as two quantiles between 0 and 1, e.g. '0.1,0.9' for an 80% interval.	No	-
--lags	Explicit lags as an int or comma-separated list, e.g. '1,2,3', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--window-features	Explicit window features as JSON array, e.g. '[{"stats": ["mean"], "window_size": 7}]', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--metric	Metric, or comma-separated metrics whose first one is the primary metric; only those are computed. 'auto' selects them from the data again when refining a saved plan.	No	-
--use-exog	Use the exogenous columns: 'true', 'false' (forecast then takes no --exog) or 'auto' for the rule.	No	-
--differentiation	Order of differencing of the target before training (an integer of at least 1), or 'auto' for the rule (no differencing). Machine learning forecasters only.	No	-
--calendar-features	Comma-separated calendar features (e.g. 'month,day_of_week'), 'none' for none, or 'auto' for those selected from the frequency. Machine learning forecasters only.	No	-
--target-transformer	Scaler of the target: 'StandardScaler', 'none', or 'auto' for the rule. Machine learning forecasters only.	No	-
--dropna-from-series	Drop the training rows with missing values: 'true', 'false' or 'auto' for the rule. Machine learning forecasters only.	No	-
--initial-train-size	Initial training window: number of observations or an ISO date marking the end of the initial training set.	No	-
--fold-stride	Fold stride (step size between folds).	No	-
--refit / --no-refit	Whether to refit the model each fold (default: decided by the assistant).	No	-
--fixed-train-size / --expanding-train	Fixed or expanding training window when the forecaster is refitted; needs --refit (default: decided by the assistant).	No	-
--gap	Gap between training and test sets.	No	-
--allow-incomplete-fold / --no-incomplete-fold	Allow last fold with fewer observations (default: decided by the assistant).	No	-
--from-plan	Load plan bundle from JSON file or '-' for stdin.	No	-
--format [code|json]	Output format: code or json.	No	code
-o, --output	Write output to file.	No	-
-q, --quiet	Suppress spinners.	No	False

forecast

Run end-to-end forecasting and report predictions, plus metrics with --test-size.

Usage

skforecast-ai forecast [OPTIONS] {data}

Arguments

Name	Description	Required
data	Path or URL to CSV file.	Yes

Options

Name	Description	Required	Default
-t, --target	Target column name(s), comma-separated.	No	-
--steps	Forecast horizon (number of steps).	No	-
-d, --date-column	Date/timestamp column.	No	-
-s, --series-id-column	Series identifier column.	No	-
--forecaster	Override forecaster class.	No	-
--estimator	Override estimator class, or the Hugging Face model ID for ForecasterFoundation (e.g. 'google/timesfm-3.0-pytorch').	No	-
--estimator-kwargs	Estimator hyperparameters as JSON string, e.g. '{"n_estimators": 200}'.	No	-
--interval	Prediction interval as two quantiles between 0 and 1, e.g. '0.1,0.9' for an 80% interval.	No	-
--lags	Explicit lags as an int or comma-separated list, e.g. '1,2,3', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--window-features	Explicit window features as JSON array, e.g. '[{"stats": ["mean"], "window_size": 7}]', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--metric	Metric, or comma-separated metrics whose first one is the primary metric; only those are computed. 'auto' selects them from the data again when refining a saved plan.	No	-
--use-exog	Use the exogenous columns: 'true', 'false' (forecast then takes no --exog) or 'auto' for the rule.	No	-
--differentiation	Order of differencing of the target before training (an integer of at least 1), or 'auto' for the rule (no differencing). Machine learning forecasters only.	No	-
--calendar-features	Comma-separated calendar features (e.g. 'month,day_of_week'), 'none' for none, or 'auto' for those selected from the frequency. Machine learning forecasters only.	No	-
--target-transformer	Scaler of the target: 'StandardScaler', 'none', or 'auto' for the rule. Machine learning forecasters only.	No	-
--dropna-from-series	Drop the training rows with missing values: 'true', 'false' or 'auto' for the rule. Machine learning forecasters only.	No	-
--test-size	Evaluation test set size: int (last N obs), float in (0,1) (fraction), or a date (test set start). The test set must hold exactly --steps observations. When omitted, forecasts the future.	No	-
--exog	CSV with future exogenous values covering the forecast horizon (prediction mode only).	No	-
--from-plan	Load plan bundle from JSON file or '-' for stdin.	No	-
--output-predictions	Save predictions as CSV.	No	-
--output-code	Save generated script to file.	No	-
--format [table|json]	Output format: table or json.	No	table
-q, --quiet	Suppress spinners.	No	False

backtest

Run backtesting evaluation and report metrics and predictions.

Usage

skforecast-ai backtest [OPTIONS] {data}

Arguments

Name	Description	Required
data	Path or URL to CSV file.	Yes

Options

Name	Description	Required	Default
-t, --target	Target column name(s), comma-separated.	No	-
--steps	Forecast horizon (number of steps).	No	-
-d, --date-column	Date/timestamp column.	No	-
-s, --series-id-column	Series identifier column.	No	-
--forecaster	Override forecaster class.	No	-
--estimator	Override estimator class, or the Hugging Face model ID for ForecasterFoundation (e.g. 'google/timesfm-3.0-pytorch').	No	-
--estimator-kwargs	Estimator hyperparameters as JSON string, e.g. '{"n_estimators": 200}'.	No	-
--interval	Prediction interval as two quantiles between 0 and 1, e.g. '0.1,0.9' for an 80% interval.	No	-
--lags	Explicit lags as an int or comma-separated list, e.g. '1,2,3', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--window-features	Explicit window features as JSON array, e.g. '[{"stats": ["mean"], "window_size": 7}]', or 'auto' to re-run the deterministic selection when refining a saved plan.	No	-
--metric	Metric, or comma-separated metrics whose first one is the primary metric; only those are computed. 'auto' selects them from the data again when refining a saved plan.	No	-
--use-exog	Use the exogenous columns: 'true', 'false' (forecast then takes no --exog) or 'auto' for the rule.	No	-
--differentiation	Order of differencing of the target before training (an integer of at least 1), or 'auto' for the rule (no differencing). Machine learning forecasters only.	No	-
--calendar-features	Comma-separated calendar features (e.g. 'month,day_of_week'), 'none' for none, or 'auto' for those selected from the frequency. Machine learning forecasters only.	No	-
--target-transformer	Scaler of the target: 'StandardScaler', 'none', or 'auto' for the rule. Machine learning forecasters only.	No	-
--dropna-from-series	Drop the training rows with missing values: 'true', 'false' or 'auto' for the rule. Machine learning forecasters only.	No	-
--initial-train-size	Initial training window: number of observations or an ISO date marking the end of the initial training set.	No	-
--fold-stride	Fold stride (step size between folds).	No	-
--refit / --no-refit	Whether to refit the model each fold (default: decided by the assistant).	No	-
--fixed-train-size / --expanding-train	Fixed or expanding training window when the forecaster is refitted; needs --refit (default: decided by the assistant).	No	-
--gap	Gap between training and test sets.	No	-
--allow-incomplete-fold / --no-incomplete-fold	Allow last fold with fewer observations (default: decided by the assistant).	No	-
--prompt	Deployment scenario in natural language; the LLM translates it into the cross-validation strategy.	No	-
--llm	LLM provider and model, e.g. 'openai:gpt-5.5'.	No	-
--base-url	Custom LLM endpoint: server URL for ollama or an OpenAI-compatible API, AWS region for bedrock.	No	-
--api-key	API key for the LLM provider.	No	-
--from-plan	Load plan bundle from JSON file or '-' for stdin.	No	-
--output-predictions	Save predictions as CSV.	No	-
--output-code	Save generated script to file.	No	-
--format [table|json]	Output format: table or json.	No	table
-q, --quiet	Suppress spinners.	No	False

compare

Compare several forecasters and report a ranked leaderboard.

Usage

skforecast-ai compare [OPTIONS] {data}

Arguments

Name	Description	Required
data	Path or URL to CSV file.	Yes

Options

Name	Description	Required	Default
-t, --target	Target column name(s), comma-separated.	No	-
--steps	Forecast horizon (number of steps).	No	-
-d, --date-column	Date/timestamp column.	No	-
-s, --series-id-column	Series identifier column.	No	-
--candidates	Candidate configs as JSON array of [name, config] pairs; config keys: forecaster, estimator, estimator_kwargs, lags, window_features, use_exog, differentiation, calendar_features, target_transformer, dropna_from_series. When omitted, candidates are built from the profile.	No	-
--metric	Metric(s) to compute, comma-separated. The first ranks the table.	No	-
--interval	Prediction interval as two quantiles between 0 and 1, e.g. '0.1,0.9' for an 80% interval.	No	-
--baseline / --no-baseline	Add a seasonal naive baseline (ForecasterEquivalentDate) to the leaderboard. Single series only.	No	baseline
--initial-train-size	Initial training window: number of observations or an ISO date marking the end of the initial training set.	No	-
--fold-stride	Fold stride (step size between folds).	No	-
--refit / --no-refit	Whether to refit the model each fold (default: decided by the assistant).	No	-
--fixed-train-size / --expanding-train	Fixed or expanding training window when the forecaster is refitted; needs --refit (default: decided by the assistant).	No	-
--gap	Gap between training and test sets.	No	-
--allow-incomplete-fold / --no-incomplete-fold	Allow last fold with fewer observations (default: decided by the assistant).	No	-
--from-profile	Load profile from JSON file or '-' for stdin.	No	-
--output-code	Save the winning configuration's script to file.	No	-
--format [table|json]	Output format: table or json.	No	table
-q, --quiet	Suppress spinners.	No	False

ask

Ask a forecasting question using an LLM.

Usage

skforecast-ai ask [OPTIONS] {prompt}

Arguments

Name	Description	Required
prompt	Natural-language question about forecasting.	Yes

Options

Name	Description	Required	Default
--data	Path to a CSV file to profile; the LLM receives its profile, never the observations.	No	-
-t, --target	Target column name(s), comma-separated.	No	-
-d, --date-column	Date/timestamp column.	No	-
-s, --series-id-column	Series identifier column.	No	-
--steps	Forecast horizon. With --data, also builds a plan so the question is answered about the plan.	No	-
--from-profile	Load profile from JSON file or '-' for stdin.	No	-
--from-plan	Load plan bundle from JSON file or '-' for stdin.	No	-
--llm	LLM provider and model, e.g. 'openai:gpt-5.5'.	No	-
--base-url	Custom LLM endpoint: server URL for ollama or an OpenAI-compatible API, AWS region for bedrock.	No	-
--api-key	API key for the LLM provider.	No	-
--send-data-to-llm / --no-send-data-to-llm	Accepted for parity with the Python API; the CLI never sends observations to the LLM, whatever its value.	No	-
--skills	Comma-separated skill names to include, e.g. 'prediction-intervals'. The Skills page of the documentation lists them.	No	-
--format [text|json]	Output format: text or json.	No	text
-q, --quiet	Suppress spinners.	No	False

check-llm

Check how the LLM configuration resolves and whether it can be used.

Usage

skforecast-ai check-llm [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
--llm	LLM provider and model, e.g. 'openai:gpt-5.5'.	No	-
--base-url	Custom LLM endpoint: server URL for ollama or an OpenAI-compatible API, AWS region for bedrock.	No	-
--api-key	API key for the LLM provider.	No	-
--test-call	Send a one-line prompt to the model once the static checks pass.	No	False
--format [table|json]	Output format: table or json.	No	table
-q, --quiet	Suppress spinners.	No	False

mcp

Serve the deterministic workflow to MCP clients (coding agents) over stdio.

Usage

skforecast-ai mcp [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
--allow-dir	Directory the server may read data from (required unless --allow-project-dir is given). Only absolute paths of CSV files inside it are accepted, also after resolving symbolic links.	No	-
--allow-project-dir	Use as the directory of --allow-dir the project of the session, read from the environment variable CLAUDE_PROJECT_DIR that Claude Code sets. The home directory and the root of a file system are rejected.	No	False
--output-dir	Directory of the files the server writes; also its working directory. Default: a new temporary directory.	No	-
--max-objects	Most objects the server keeps; the least recently used ones are removed beyond it.	No	256
--max-memory-mb	Memory, in MB, the objects may take; the least recently used ones are removed beyond it.	No	1024
--max-file-mb	Largest CSV file the server reads, in MB, checked before reading it (also on the content of a '.gz' file); 0 for no limit.	No	256
--allow-model	Model ID prefix of a foundation model that the server may run although its license restricts commercial use, its weights are gated, its provider requires an account or skforecast gives no license information, e.g. google/timesfm-3.0 (repeatable). Other models run without it.	No	-

config

Manage persistent configuration.

Usage

skforecast-ai config [OPTIONS] COMMAND [ARGS]...

Arguments

No arguments available

Options

No options available

Subcommands

show

Display current configuration.

Keys that skforecast-ai does not read (left by an older version or written by hand) are listed as ignored instead of being shown as if they had an effect.

Returns

None

Usage

skforecast-ai config show [OPTIONS]

Arguments

No arguments available

Options

No options available

set

Set a configuration value.

Parameters

key : str Config key in dotted notation (e.g. 'llm.provider'). value : str Value to set.

Returns

None

Usage

skforecast-ai config set [OPTIONS] {key} {value}

Arguments

Name	Description	Required
key	Config key (e.g. 'llm.provider').	Yes
value	Value to set.	Yes

Options

No options available

path

Print the config file location.

Returns

None

Usage

skforecast-ai config path [OPTIONS]

Arguments

No arguments available

Options

No options available