Intro

The Acurast CLI helps you to deploy apps on the Acurast Cloud.

Installation

To install the Acurast CLI, you can use npm:

npm install -g @acurast/cli

Usage

To use the Acurast CLI, type acurast followed by any of the available options or commands.

Options

• -v, --version - Output the version number.
• -h, --help - Display help for command.

Commands

• new <project-name> - Create a new Acurast project from a template.
• deploy [options] [project] - Deploy the current project to the Acurast platform.
• deployments <'ls' | <id>> --cleanup - List, view and clean up deployments.
• live [options] [project] - Setup a "live-code-processor" and run your project on the processor in real time.
• init - Create an acurast.json file and .env file.
• open - Open the Acurast resources in your browser.
• help [command] - Display help for command.

Configuration

Example Configuration

The acurast.json file is generated by running acurast init. Here is an example configuration:

{
  "projects": {
    "example": {
      "projectName": "example",
      "fileUrl": "dist/bundle.js",
      "network": "canary",
      "onlyAttestedDevices": true,
      "assignmentStrategy": {
        "type": "Single"
      },
      "execution": {
        "type": "onetime",
        "maxExecutionTimeInMs": 10000
      },
      "maxAllowedStartDelayInMs": 10000,
      "usageLimit": {
        "maxMemory": 0,
        "maxNetworkRequests": 0,
        "maxStorage": 0
      },
      "numberOfReplicas": 64,
      "requiredModules": [],
      "minProcessorReputation": 0,
      "maxCostPerExecution": 100000000000,
      "includeEnvironmentVariables": [],
      "processorWhitelist": []
    }
  }
}

This is the configuration that is read when acurast deploy is called and the app is deployed according to those parameters.

Additionaly, a .env file is generated that will hold some of the secrets to deploy the app, and also any environmnet variables that you may want to add to your deployment.

ACURAST_MNEMONIC=abandon abandon about ...
# ACURAST_IPFS_URL=https://api.pinata.cloud
# ACURAST_IPFS_API_KEY=eyJhb...
# ACURAST_RPC=wss://...

Configuration Details

acurast.json

• projectName: The name of the project.
• fileUrl: The path to the bundled file, including all dependencies (e.g., dist/bundle.js).
• network: The network on which the project will be deployed. (e.g. canary)
• onlyAttestedDevices: A boolean to specify if only attested devices are allowed to run the app.
• startAt: The start time of the deployment.
  • msFromNow: The deployment will start the specified number of milliseconds from now.
  • timestamp: The deployment will start at the specified timestamp.
• assignmentStrategy: Defines the assignment strategy, which can be:
  • type: AssignmentStrategyVariant.Single: Assigns one set of processors for a deployment. If instantMatch is provided, specifies processors and maximum allowed start delay:
    • processor: Processor address.
    • maxAllowedStartDelayInMs: Maximum allowed start delay in milliseconds.
  • type: AssignmentStrategyVariant.Competing: Assigns a new set of processors for each execution.
• execution: Specifies the execution details, which can be:
  • type: 'onetime'`: Run the deployment only once.
    • maxExecutionTimeInMs: Maximum execution time in milliseconds.
  • type: 'interval'`: Multiple executions for the deployment.
    • intervalInMs: Interval in milliseconds between each execution start.
    • numberOfExecutions: The number of executions.
    • maxAllowedStartDelayInMs: Specifies the maximum allowed start delay (relative to the starting time) of the deployment in milliseconds.
• usageLimit: The usage limits for the deployment:
  • maxMemory: Maximum memory usage in bytes.
  • maxNetworkRequests: Maximum number of network requests.
  • maxStorage: Maximum storage usage in bytes.
• numberOfReplicas: The number of replicas, specifying how many processors will run the deployment in parallel.
• requiredModules: Modules that the processor needs to support to run the deployment (e.g., ['DataEncryption'] or []).
• minProcessorReputation: The minimum required reputation of the processor.
• maxCostPerExecution: The maximum cost per execution in the smallest denomination of cACUs.
• includeEnvironmentVariables: An array of environment variables in the .env file that will be passed to the deployment.
• processorWhitelist: A whitelist of processors that can be used for the deployment.
• minProcessorVersions: The minimum processor versions that will be used for the deployment.
  • android: The minimum Android version.
  • ios: The minimum iOS version.

.env

ACURAST_MNEMONIC: The mnemonic used to deploy the app. Make sure the account has some cACU! You can claim some on the faucet. ACURAST_IPFS_URL (optional): The URL of the IPFS gateway, eg. https://api.pinata.cloud. ACURAST_IPFS_API_KEY (optional): The API key to access the IPFS gateway. You can register here to get an API key. ACURAST_RPC (optional): Set an RPC URL to connect to.

Live Code Feature

For easier development of acurast deployments, we added a feature that we call "Live Code". To use this feature, you can dedicate one or multiple processors to run a piece of code for an extended period of time, which can then on-demand execute your code and return the result. This makes development and debugging a lot faster because you can see console.logs and errors.

To get started, you first have to set up a processor to run the live-code deployment. You can do this by running

acurast live --setup

During setup, you can choose the duration of the deployment.

Follow the instructions in the CLI. There is currently a step where a public key has to be manually copy/pasted from the web-console. This step will soon be fully automated.

After the deployment has started (after 5 minutes), you can then run

acurast live

This will run your project in the live-processor. It will use the same configuration that was set up during the acurast init step.

Environment Variables

You can use environment variables in Acurast depoyments. The environment variables that are encrypted during deployment and only decrypted when the code is run on the processor. This is useful for storing sensitive information like API keys.

To use environment variables in your project, you first need to add them to the .env file like this:

API_KEY=your-api-key

To configure which of your deployments make use of the environment variables, edit the acurast.json file and add all the environment variables to be included to the includeEnvironmentVariables array.

{
  "projects": {
    "tutorial": {
      "projectName": "tutorial",
      "fileUrl": "dist/bundle.js",
      "network": "canary",
      "onlyAttestedDevices": true,
      "assignmentStrategy": {
        "type": "Single"
      },
      "execution": {
        "type": "onetime",
        "maxExecutionTimeInMs": 60000
      },
      "maxAllowedStartDelayInMs": 10000,
      "usageLimit": {
        "maxMemory": 0,
        "maxNetworkRequests": 0,
        "maxStorage": 0
      },
      "numberOfReplicas": 1,
      "requiredModules": [],
      "minProcessorReputation": 0,
      "maxCostPerExecution": 1000000000,
      "includeEnvironmentVariables": ["API_KEY"],
      "processorWhitelist": []
    }
  }
}

Then, in your code, you can access the environment variables like this:

const API_KEY = _STD_.env[API_KEY]

When running acurast deploy, the environment variables will now automatically be added to the deployment.

When running interval based deployments with multiple executions, the environment variables can be updated between executions. To do that, update the .env file and run acurast deployments <id> -e. This will update the environment variables for the deployment with the given ID.

Development

To contribute to the development of Acurast CLI, follow these steps:

Clone the repository:

git clone https://github.com/acurast/acurast-cli.git

Navigate to the project directory:

cd acurast-cli

Install the dependencies:

npm install

After making your changes, you can run tests using:

npm run test

To test your changes locally:

npm run setup

After this command, acurast will be available globally on your computer.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request.