CLI Usage

CLI Usage


Welcome to fxhash
Web3 Fundamentals
The fxhash Ecosystem

Getting Started

Initial Setup
Product Overview

Artist Guides

Project Setup and Artist Tools
The fx(hash) API
Generative Art with fx(params)
Browser Based Generative Art
Releasing your Project

CLI Usage

In this section we have a brief look at how to use the CLI, and will have a more detailed look at the individual CLI commands.

Overview of the different CLI commands

Here’s a quick overview of the different CLI commands and the options that can be attached to them:

fxhash create Creates a blank fx(hash) project. Allows you to choose between several starting templates.
fxhash dev [options] Starts a development environment for the artwork. Each time fxhash dev is run the environment will check for updates and will keep itself up-to-date.
The port fxlens is served on. Default: 3300
The port the project is served on. Default: 3301
The path to the source of the project. This is just relevant for ejected projects that actually have a nested structure. Default: /src
fxhash build [options] Creates a bundled version of the project directory. The output file will be called and can be uploaded as it is on
Enable minification when creating the bundle. Default: false
Disable the zip file creation. Default: false
The path to the source of the project. This is just relevant for ejected projects that actually have a nested structure. Default: /src
fxhash update [options] Will update the whole fxhash environment. It will download the latest version of fxlens and the fxhash-snippet. Optionally you can inject the latest snippet into your html file.
The path to the source of the project. This is just relevant for ejected projects that actually have a nested structure. Default: /src
fxhash eject Will eject your project into a nested structure. It will copy all your code into a srcPath (Default: /src) and create a package.jsonfile in the root of your project. This will allow you to configure any custom tooling you like while still being able to use the @fxhash/cli in your ejected project.
The path to eject the code into. If you set a custom path here you also must specify this path to the other commands.
fxhash add <package@version> Installs existing libraries. Beside being a convenience feature. This ensure that you are reusing existing libraries from the ONCHFS, which reduces the costs of storing your project on-chain 😎.
Lists all existing libraries that can be imported
Will also inject a <script /> tag into your projects html entry point pointing to the downloaded library
fxhash capture [args] With the capture command you can test your bundled project agains the fx(hash) capture module. For params token you currently must provide the inputBytes yourself. You can copy the inputBytes from the url when you are running the fxhash dev command.
The path (absolute or relative) to the project's zip file you want to create the capture of. Default:
The hash that is injected when the capture is taken. Default: random value
The minter address that is injected when the capture is taken. Default: random value
The iteration number that is injeted when the capture is taken. Default: 1
The inputBytes that are injected when the capture is taken. Default: undefined
The width in pixels. Capped at 2560. Default: 800
The height in pixels. Capped at 2550. Default: 800
The trigger mode. Either DELAY or FN_TRIGGER. Default: delay
The delay in ms for the trigger mode DELAY. Default: 3000
The id of the canvas element to capture.

Creating a new Project with fx(hash) create

Once you've installed the CLI there's no need to clone the starting template from github anymore, you can simply create a new fxhash project with the fxhash create command. Entering that command into your terminal, it will ask you to provide a name for your project and choose a template. Currently there are two templates:

  • Simple Template: If you are new to the platform and/or don't need any special customization, we recommend starting with the simple template.
  • The Ejected Template: Needs an explanation of the ejected template

Completing these two steps will then spawn a new folder in the current terminal directory, this directory will contain a bunch of files. In case of the simple template it's essentially the boilerplate.


Running the fxhash create command in the terminal + the files that it spawns

The fxhash create command has no options.

Starting the Development Environment with fxhash dev

The fxhash dev command should be run from within the directory that is created with the fxhash create command, it requires an index.html file to run. This will launch the fx(hash) development environment and will automatically open a new tab in your default browser. If you haven’t already written some code for your artwork in the index.js, it will show the following default screen:


Running the default starting template will display a bunch of text in the main area of the browser window, later this will be replace by our artwork.

The panel on the left-hand side is fx(lens), fx(hash)’s interactive project viewer that comes out of the box with the CLI. fx(lens) is explained in more detail here, it provides a number of functionalities for testing the determinism of your generative artwork and is an important tool for building fx(params) pieces.

Building the Project with fxhash build

When your artwork is ready for being minted it should be uploaded to fx(hash) in the form of a .zip file. The CLI provides the fxhash build command that bundles all of your project files as such a .zip. This will create an file in your project directory, that can later be drag-n-dropped into the fx(hash) minting interface.

Before you upload a project to fx(hash) however make sure to read the rest of the artist guides to ensure that your project works correctly and is properly configured to be compatible with the platform. fx(hash) can not check this for you.

Testing Captures with fxhash capture

The CLI also lets you test the appearance of your project once it’s iterations have been collected on fx(hash). For this you’ll first have to bundle your project with the fxhash build command, to then subsequently run the fxhash capture command which will then generate a jpg of the artwork, here’s what this would look like:


The capture command provides a number of options to specify some of the information that needs to be fed into the token to generate specific captures, and to control how the capture should be taken. They are detailed in the overview table above.

Updating the CLI with fxhash update

The fxhash update command will update the CLI and all of it’s features to the latest version:


Here you might have to use the sudo command again, because updating requires overwriting files in the directory that the CLI is installed in.

Configuration with .env

The CLI accepts a .env file in the root folder. The .env file allows you to configure all options of the CLI and store them for your project, here’s an example:


This is useful when you want to set the default behaviour of different commands without having to type out the options every single time.

Arguments passed to the command will always override the variables set in the .env file

← Previous

CLI Setup

Next →