Getting Started

You can watch a video tutorial if you prefer a visual guide on how to create a project and start writing your first automation.

Otherwise, follow the steps below to get started with ZapCLI.

1. Install the CLI

   Start by installing the CLI globally using your preferred package manager.

   npm

   npm install @zapcli/cli -g

   yarn

   yarn global add @zapcli/cli

   pnpm

   pnpm install @zapcli/cli -g

2. Create a project

   Generate a new project using zapcli. This action will set up a sample project and install all necessary dependencies.

   zapcli create MyProject

   After running the command, you will see a new directory named MyProject with the following structure:

   • Directorydata/

     • …
   • Directoryreport/

     • data.json
     • report.html
   • Directorysrc/

     • hello.zp
     • hello.js
   • package.json
   • zp.config.js

   Open your project in VSCode or any other editor.

3. Run automation

   ZapCLI can execute an automation once on a specific day and showcase the orders in the terminal or store them in a file (e.g., orders.json). To run an automation just open it in VSCode (src/hello.zp) and press Ctrl+Shift+B. Or you can use the terminal:

   zapcli

   zapcli execute ./src/hello.zp

   npm

   npm execute

4. Run your first backtest

   zapcli

    zapcli backtest ./src/hello.zp

   npm

   npm backtest

   This command will execute hello.zp for a duration of 20 days. It will display the result in the terminal and save the backtest data in backtests/data.json. You can change the directory where the backtest data is saved by changing the backtestsDir property in the zp.config.js file.

5. Generate a report

   zapcli

    zapcli report

   npm

   npm report

   This command will generate a visual report file reports/report.html based on the backtest data saved in backtests/ directory. You can generate multiple reports by providing the name parameter.

6. Write your own automation

   To write your own strategy you need to create an automation file that will be run on every bar. Currently we have been using the hello.(zp|js) file

   hello.zp

   ;; Loops a list a symbols and buys 1 share of each
   
   (def symbols [
       "AAPL",
       "MSFT"
   ])
   
   (loop symbol in symbols
       (buy {symbol} 1)
   )

   hello.js

   const assets = ["AAPL", "MSFT"]
   const window = 1
   const settings = {}
   
   function run() {
       for (const symbol of assets) {
           this.buy(this.asset(symbol), 1)
       }
   }

   To see more automation examples check out the Examples page.

7. Configuration

   ZapCLI is using a configuration file to run a backtest or execute an automation file. Your project started with the default config file:

   import { analyzers } from '@zapcli/backtest'
   
   const config = {
   // Directories
   dataDir: "./data",
   reportsDir: "./reports",
   backtestsDir: "./backtests",
   
   // Data Provider
   // ex. zapcli download -s AAPL
   dataProvider: "zapant",
   
   // Execute automation
   // ex. zapcli execute
   execute: {
       date: "2024-05-20",
       inputs: {
       assets: ["AAPL", "MSFT"],
       initialCapital: 10000,
       cash: 5000,
       openPositions: [
           // Provide open positions to automation
           // {
           //   symbol: 'AAPL',
           //   openDate: 1682366400000,
           //   openPrice: 200.00,
           //   closeDate: null,
           //   closePrice: null,
           //   units: 5,
           //   side: 'long',
           //   accountType: 'paper'
           // }
       ]
       },
   },
   // Backtest automation
   // ex. zapcli backtest
   backtest: {
       startDate: "2024-05-01",
       endDate: "2024-05-20",
       inputs: {
       assets: []
       },
       analyzers: [
           new analyzers.RetursAnalyzer(),
           new analyzers.DrawDownAnalyzer(),
           new analyzers.TradesAnalyzer(),
           new analyzers.PositionsAnalyzer(),
       ]
   }
   }
   
   export default config;

   As you can see here you can configure your backtest with a start, end date or add analyzers to run with your backtest. To learn more about Analyzers and Data Providers please read the documentaion.