Essentials
Getting Started
Artist Guides
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:
Command | Options | Effect |
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. | --portStudio | The port fxlens is served on. Default: 3300 |
--portProject | The port the project is served on. Default: 3301 | |
--srcPath | 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 upload.zip and can be uploaded as it is on fxhash.xyz. | --minify | Enable minification when creating the bundle. Default: false |
--noZip | Disable the zip file creation. Default: false | |
--srcPath | 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. | --srcPath | 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. | --srcPath | 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 😎. | --list | Lists all existing libraries that can be imported |
--inject | 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. | --zip | The path (absolute or relative) to the project's zip file you want to create the capture of. Default: upload.zip |
--hash | The hash that is injected when the capture is taken. Default: random value | |
--minter | The minter address that is injected when the capture is taken. Default: random value | |
--iteration | The iteration number that is injeted when the capture is taken. Default: 1 | |
--inputBytes | The inputBytes that are injected when the capture is taken. Default: undefined | |
--x | The width in pixels. Capped at 2560. Default: 800 | |
--y | The height in pixels. Capped at 2550. Default: 800 | |
--trigger | The trigger mode. Either DELAY or FN_TRIGGER. Default: delay | |
--delay | The delay in ms for the trigger mode DELAY. Default: 3000 | |
--selector | 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 upload.zip file in your project directory, that can later be drag-n-dropped into the fx(hash) minting interface.
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:
PORT_PROJECT=3301
PORT_STUDIO=3300
SRC_PATH=/src
MINIFY=falseThis is useful when you want to set the default behaviour of different commands without having to type out the options every single time.
.env file