Directory Structure


Although we provide an opinionated directory structure, your application can theoretically be arranged in any way you like as no paths are hardcoded.
The only exceptions to this are the location of your .env file and the structure of your commands directory, which must follow the Topics pattern defined by the OCLIF framework.

Application Structure

  • app/
    • commands/
    • config/
    • contracts/
    • hooks/
    • modules/
      • acts/
      • auditions/
      • exceptions/
    • providers/
    • schemas/
    • templates/
  • bin/
  • prisma/
  • storage/
  • test/
    • commands/

Root directory

The project root contains the following important files.
IDE helper file to unify with framework patterns.
Your environment-specific key-value config.
.eslintrc / .eslintignore
Unifies your code style with the framework.
Informs git to avoid committing certain files.
Allows npm overrides, such as avoiding default Chromium download with Puppeteer.
.prettierrc / .prettierignore
Tool to help enforce clean code standards on the project.
Used to configure your package.
Defines TypeScript build settings.

App directory

Your application's root directory. All files in this directory will be compiled by TypeScript and exported to the lib directory.


When you run a command from the CLI, the OCLIF framework will look for matches in this directory. Think about commands like the entry-points to your app.


Contains your configuration files which can be created fresh or extended from the Backstage framework core configurations.


Your TypeScript typings. Any changes to the shape of your classes should be modified here.


Any hooks you would like to define for the command lifecycle. Any new hooks must be added to your package.json file.
Available lifecycle stages defined by OCLIF are init, prerun,postrun, and command_not_found


Modules directory can contain any number of miscellaneous groupings, however, some common ones are predefined.


The collection of your automation logic, grouped into Acts and Scenes.


Tests against known detection vendors to analyse the effectiveness of your bot and operational environment.


Define custom exceptions here to make throwing errors cleaner and strongly typed.


All Service Providers should be located in this directory and exported from the index. Most of the core Backstage providers are extended here by default to allow customisation, however any number of providers can be implemented depending on the needs of your application.


Your Zod validation logic should be defined here. You can define validation scopes however you like, but we recommend one file per scope.


You can customise your make: command templates here. We looked at several templating packages, however nearly all are designed for generating HTML rather than JavaScript files, so we opted to use native ES6 templating syntax.

Prisma directory

Prisma is the recommended database driver for your application. The configuration files and any flat file sqlite databases should be defined here.
We recommend reading more about Prisma in their docs before getting started.

Storage Directory

The storage directory is a folder for transient data such as screenshots and profiles (i.e. userDataDir). It can be structured however you like, however if you are using the Profiles module we recommend against renaming the profiles subdirectory.

Test directory

This directory contains your applications Mocha tests. More information about writing and running tests is covered in the Testing section.