Running Scripts

The run command executes Pyne code on OHLCV data from a file or from a data provider plugin, optionally continuing with live data. This page covers the details of how to use this command effectively.

Basic Usage

The basic syntax for running a script is:

pyne run SCRIPT DATA [OPTIONS]

Where:

  • SCRIPT: Path to the Pyne code (.py) or to a Pine Script (.pine) file that is converted to Pyne code first
  • DATA: Path to the data file (.ohlcv, .csv, .json, or .txt), or a provider string (see Provider Mode)
  • OPTIONS: Additional options to customize the execution

Simple Example 

# Run a script using paths within the working directory
pyne run my_strategy.py eurusd_data.ohlcv

This command will:

  1. Look for my_strategy.py in the workdir/scripts/ directory
  2. Look for eurusd_data.ohlcv in the workdir/data/ directory
  3. Execute the script with the provided data
  4. Save outputs to the workdir/output/ directory

Pine Script Support

You can also pass a Pine Script (.pine) file: PyneCore sends it to PyneComp, the PyneSys conversion service, which converts it to Pyne code (.py), and then runs that code. When you specify a .pine file:

  1. Automatic Compilation: The .pine file is compiled to Pyne code if:

    • The .py file doesn’t exist, or
    • The .pine file is newer than the existing .py file

  2. API Key Required: A valid PyneSys API key is required for Pine Script compilation. You can get one at https://pynesys.io. Without an API key, run uses an existing .py file next to the .pine file and does not recompile.

  3. Output Location: The compiled .py file is saved in the same folder as the original .pine file.

Pine Script Example 

# Convert a Pine Script with PyneComp, then run the resulting Pyne code
pyne run my_strategy.pine eurusd_data.ohlcv

This command will:

  1. Check if my_strategy.py exists and is up-to-date
  2. If not, compile my_strategy.pine to my_strategy.py using the PyneSys API
  3. Run the resulting Pyne code with the provided data

API Key Configuration

For Pine Script compilation, you can provide the API key in several ways:

  1. Command line option: Use the --api-key flag
  2. Environment variable: Set PYNESYS_API_KEY
  3. Configuration file: Store in workdir/config/api.toml

Example with API key:

# Run Pine Script with API key
pyne run my_strategy.pine eurusd_data.ohlcv --api-key "your-api-key"

Automatic Data Conversion

The run command now supports automatic conversion of non-OHLCV data formats. When you provide a CSV, JSON, or TXT file, the system automatically:

  1. Detects the file format from the extension
  2. Analyzes the filename to extract symbol and provider information
  3. Converts the data to OHLCV format
  4. Generates a TOML configuration with detected parameters
  5. Runs the script with the converted data

Supported Formats and Detection

The automatic conversion supports:

  • CSV files: Standard comma-separated values
  • JSON files: JSON formatted OHLCV data
  • TXT files: Tab, semicolon, or pipe-delimited data

Filename Pattern Detection

The system recognizes common filename patterns:

  • BTCUSDT.csv → Symbol: BTC/USDT
  • EUR_USD.json → Symbol: EURUSD
  • ccxt_BYBIT_BTC_USDT.csv → Symbol: BTC/USDT, Provider: bybit
  • BINANCE_ETHUSDT_1h.csv → Symbol: ETH/USDT, Provider: binance

Example with Automatic Conversion 

# Run a script with CSV data (automatic conversion)
pyne run my_strategy.py BTCUSDT.csv

# The system will:
# 1. Detect BTC/USDT as the symbol
# 2. Convert CSV to OHLCV format
# 3. Generate BTCUSDT.toml with symbol info (an existing .toml is kept
#    and must match the data's timeframe)
# 4. Run the script with converted data

Advanced Analysis During Conversion

When converting data, the system performs advanced analysis:

  • Tick Size Detection: Analyzes price movements to determine minimum price increment
  • Trading Hours Detection: Identifies when the market is actively trading
  • Timeframe Detection: Infers the bar period from the timestamps; an existing .toml with a different period stops the conversion
  • Symbol Type Detection: Identifies forex, crypto, or other asset types

Command Arguments

The run command has two required arguments:

  • SCRIPT: The script file to run. If only a filename is provided, it will be searched in the workdir/scripts/ directory.
  • DATA: The data file to use. Supports .ohlcv, .csv, .json and .txt files, or a provider string (see Provider Mode). If only a filename is provided, it will be searched in the workdir/data/ directory.
Note: file extensions are optional. A script name tries `.pine` first, then `.py`; a data name tries `.ohlcv`, then `.csv`.

Provider Mode

Instead of a local data file, you can pass a provider string as the DATA argument. The provider plugin downloads historical data and (with --live) streams real-time updates:

# Download historical data from CCXT/Bybit and run the script
pyne run my_strategy.py ccxt:BYBIT:BTC/USDT:USDT@1

# Same, but continue with live streaming after the historical phase
pyne run my_strategy.py ccxt:BYBIT:BTC/USDT:USDT@1 --live -f -500

The built-in ccxt provider needs the ccxt extra:

pip install "pynesys-pynecore[ccxt]"

Provider string format: provider:EXCHANGE:SYMBOL:SETTLE@TIMEFRAME

PartExampleDescription
providerccxtPlugin name (entry point)
EXCHANGEBYBITExchange identifier
SYMBOLBTC/USDTTrading pair
SETTLEUSDTSettlement currency (optional)
TIMEFRAME1TradingView timeframe format

The EXCHANGE segment is the broker selector for multi-broker providers (CCXT covers 100+ exchanges); a single-broker provider plugin omits it (provider:SYMBOL@TIMEFRAME). The same provider string works with pyne data download, which can also list a provider’s brokers via --list-brokers.

The -f / --from option accepts a negative integer for relative bar count when using a provider string:

# Prefetch the last 500 bars
pyne run script.py ccxt:BYBIT:ETH/USDT:USDT@5 -f -500

See Live Mode for details on real-time streaming, intra-bar updates, strategy suppression, and paper trading.

Command Options

The run command supports several options to customize the execution:

Compilation Options

  • --api-key, -a: PyneSys API key for Pine Script compilation (overrides configuration file)

Date Range Options

  • --from, -f: Start date (UTC) in ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’ format, or a positive number of days back from now (e.g. -f 30). If not specified, it will use the first date in the data. In provider mode, also accepts a negative integer for relative bar count (e.g. -f -500); defaults to -500 bars if omitted.
  • --to, -t: End date (UTC) in ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’ format, or a positive number of days back from now (e.g. -t 7). If not specified, it will use the last date in the data.

Example:

# Run a script for a specific date range
pyne run my_strategy.py eurusd_data.ohlcv --from "2023-01-01" --to "2023-12-31"

Live Mode Options

  • --live, -l: Continue with real-time data streaming after the historical phase. Only available in provider mode (provider string as data source). See Live Mode.
  • --broker: Enable live broker trading. Requires a provider plugin that supports broker trading (subclasses BrokerPlugin). Implies --live.
  • --run-label: Optional label to distinguish parallel instances of the same strategy, account, symbol and timeframe. Stored in the broker run ID as ...#<label>.
  • --shutdown-timeout: Maximum seconds to wait for graceful provider shutdown when stopping (default: 120; 0 waits forever).
  • --no-log-ohlcv: Disable the per-bar OHLCV log lines in live mode (enabled by default).

Example:

# Stream live 1-minute BTC/USDT bars after 500 historical bars
pyne run my_strategy.py ccxt:BYBIT:BTC/USDT:USDT@1 --live -f -500

Output Path Options

  • --plot, -pp: Path to save the plot data (CSV format). If not specified, it will be saved as <script_name>.csv in the workdir/output/ directory.
  • --strat, -sp: Path to save the strategy statistics (CSV format). If not specified, it will be saved as <script_name>_strat.csv in the workdir/output/ directory.
  • --trade, -tp: Path to save the trade data (CSV format). If not specified, it will be saved as <script_name>_trade.csv in the workdir/output/ directory.
  • --no-plot: Do not write the plot CSV at all. Useful in live mode, where the file grows without bound. Cannot be combined with --plot.
  • --viz, -vz: Write plot and drawing visual data (NDJSON). Saved as <script_name>_viz.ndjson in the workdir/output/ directory unless --viz-path is given.
  • --viz-path: Path of the visual data NDJSON file (implies --viz).
  • --viz-journal: Record per-bar drawing create/update/delete events (implies --viz).

An explicit output path is used as given: a bare file name is written to the current directory, not to workdir/output/.

Example:

# Specify custom output paths
pyne run my_strategy.py eurusd_data.ohlcv --plot custom_plot.csv --strat custom_stats.csv --trade custom_trades.csv

Timeframe Option

  • --timeframe, -tf: Chart timeframe in TradingView format (e.g. 5, 60, 1D, 1W). Must be larger than or equal to the data file’s timeframe, and an exact multiple of it (e.g. 10 → 60, not 7 → 60).

When the data timeframe is smaller than the chart timeframe:

  • Strategy with use_bar_magnifier=True: activates bar magnifier mode — the script sees aggregated chart-TF bars, but order fills are checked against each sub-bar for higher accuracy. See Bar Magnifier for details.
  • Otherwise: aggregates data on-the-fly to the chart timeframe (equivalent to pyne data aggregate but without creating a file).
# Bar magnifier: 10-minute data, 1-hour chart (strategy must have use_bar_magnifier=True)
pyne run my_strategy.py EURUSD_10m.ohlcv --timeframe 60

# On-the-fly aggregation: 1-minute data aggregated to 5-minute bars
pyne run my_indicator.py BTCUSDT_1m.ohlcv --timeframe 5

Security Data Options

If your script uses request.security() to access data from other symbols or timeframes, provide the OHLCV data for each context using --security:

  • --security, -sec: Security data mapping in "KEY=value" format. Can be specified multiple times. KEY is "TIMEFRAME" (e.g., "1D"), "SYMBOL" (e.g., "USI:ADVN.NY") or "SYMBOL:TIMEFRAME" (e.g., "AAPL:60"). In backtests the value is a data name in workdir/data/ (with or without the .ohlcv extension) or a path to an .ohlcv file; with --live it is a plugin-native symbol (e.g. binance:ETH/USDT).
  • --list-data: List the OHLCV data the script needs (from its request.security() calls) and exit without running.

Example:

# Daily data for a multi-timeframe indicator
pyne run mtf_indicator.py EURUSD_5m --security "1D=EURUSD_1D"

# Multiple symbols for an advance/decline indicator
pyne run advance_decline.py SPX_1D \
  --security "USI:ADVN.NY=USI_ADVN_NY" \
  --security "USI:DECL.NY=USI_DECL_NY"

Each security data name must have a corresponding .ohlcv and .toml file pair in the data directory.

To avoid passing --security on every run, map the symbols your script uses to your data in config/symbol_map.toml; see Symbol Map.

Symbol Information

When running a script, PyneCore needs symbol information to provide the script with details about the financial instrument being analyzed. This information is stored in a TOML file with the same name as the OHLCV file but with a .toml extension.

For example, if your data file is eurusd_data.ohlcv, the system will look for symbol information in eurusd_data.toml.

The symbol information file should be located in the same directory as the OHLCV file and contain information like:

  • Symbol name and description
  • Exchange information
  • Currency
  • Session times
  • Tick size and value
  • etc.

More details about the symbol information can be found here.

If the symbol information file is not found, the command will display an error.

Progress Tracking

When running a script, the PyneCore CLI shows a progress bar with:

  • Current date being processed
  • Elapsed time
  • Estimated remaining time
  • Visual progress indicator

Example:

✓ Running script... [██████████████████████████████] 2023-12-31 12:30:00 / 0:01:45

Output Files

After the script execution completes, several output files are created:

Plot Data (CSV)

Contains the values plotted by the script for each bar. This includes all values passed to plot() functions in your script.

Default filename: <script_name>.csv

Strategy Statistics (CSV)

If your script is a strategy, this file contains comprehensive TradingView-compatible statistics about the trading performance, including:

  • Overview metrics: Net profit, gross profit/loss, max equity runup/drawdown, buy & hold return
  • Performance ratios: Sharpe ratio, Sortino ratio, profit factor
  • Trade statistics: Total/winning/losing trades, percent profitable, average trade metrics
  • Position analysis: Largest winning/losing trades, average bars in trades
  • Long/Short breakdown: Separate statistics for long and short positions
  • Risk metrics: Max contracts held, commission paid, margin calls

Default filename: <script_name>_strat.csv

Trade Data (CSV)

If your script is a strategy, this file contains detailed trade-by-trade data with entry and exit records:

  • Trade information: Trade number, bar index, entry/exit type, signal ID
  • Timing data: Date/time of entry and exit
  • Price data: Entry/exit prices in the symbol’s currency
  • Position data: Number of contracts traded
  • Performance metrics: Profit/loss in currency and percentage
  • Cumulative tracking: Running totals of profit and profit percentage
  • Risk analysis: Maximum run-up and drawdown for each trade

Default filename: <script_name>_trade.csv

Note: This file exports individual trade records (entry/exit pairs), not the equity curve. The equity curve is tracked internally for statistics calculation.

Visual Data (NDJSON)

Only written with --viz, --viz-path or --viz-journal. Contains the plot and drawing visual data of the script.

Default filename: <script_name>_viz.ndjson

Examples

Basic Usage 

# Run a script with default options
pyne run my_strategy.py eurusd_data.ohlcv

Specifying Date Range 

# Run a script for a specific month
pyne run my_strategy.py eurusd_data.ohlcv --from "2023-03-01" --to "2023-03-31"

Custom Output Paths 

# Save outputs to custom locations
pyne run my_strategy.py eurusd_data.ohlcv \
  --plot ./analysis/my_plot.csv \
  --strat ./analysis/my_stats.csv \
  --trade ./analysis/my_trades.csv

Troubleshooting

Script File Not Found 

Script file '/path/to/workdir/scripts/my_strategy.py' not found!

This error occurs when the script file cannot be found. Make sure:

  • The file exists in the specified location
  • If you provided just a filename, check that it exists in the workdir/scripts/ directory
  • The filename is spelled correctly (case sensitive)

Data File Not Found 

Data file not found: eurusd_data.ohlcv

This error occurs when the data file cannot be found. Make sure:

  • The file exists in the specified location
  • If you provided just a filename, check that it exists in the workdir/data/ directory
  • The filename is spelled correctly (case sensitive)

Symbol Info File Not Found 

Symbol info file '/path/to/workdir/data/eurusd_data.toml' not found!

This error occurs when the symbol information file cannot be found. Make sure:

  • The file exists in the same directory as the OHLCV file
  • The filename matches the OHLCV file (with a .toml extension)
  • If you’re using a data provider, check that you’ve downloaded the symbol information