@acurast/cli

Acurast CLI

Deploy apps on the Acurast Cloud

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.
• estimate-fee [options] [project] - Estimate the fee for the current project.
• deployments [arg] [options] - List, view, and manage deployments.
  • deployments ls or deployments list - List all your deployments.
  • deployments <id> - View details of a specific deployment.
  • deployments <id> --update-env-vars - Update environment variables for a deployment.
  • deployments --cleanup - Clean up old, finished deployments.
  • deployments <id> --cleanup - Clean up a specific deployment.
  • deployments update script <deployment-id> <script-ipfs> [options] - Update the script of a mutable deployment.
  • deployments update editor <deployment-id> <new-editor-address> [options] - Transfer editor permissions for a mutable deployment.
• 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": [],
      "mutability": "Immutable",
      "reuseKeysFrom": null
    }
  }
}

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.
• mutability: The mutability of the deployment. Controls whether the deployment can be modified after creation.
  • "Immutable": The deployment cannot be modified after creation (default).
  • "Mutable": The deployment can be modified after creation.
• reuseKeysFrom: An optional array that allows reusing keys from a previous deployment, if that deployment was set to "Mutable". Format: [MultiOrigin, string, number] where:
  • First element: The origin chain (currently only "Acurast" is supported)
  • Second element: The address of the original deployer
  • Third element: The deployment ID
  • Example: ["Acurast", "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL", 123456]

.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.

Deployment Management

The Acurast CLI provides comprehensive deployment management capabilities, including the ability to update mutable deployments and transfer editor permissions.

Basic Deployment Commands

# List all deployments
acurast deployments ls

# View a specific deployment
acurast deployments "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456"

# Update environment variables for a deployment
acurast deployments "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456" --update-env-vars

# Clean up old deployments
acurast deployments --cleanup

# Clean up a specific deployment
acurast deployments "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456" --cleanup

Note: All deployment commands require the full deployment ID format: "origin:address:number"

Updating Mutable Deployments

For deployments that were created with "mutability": "Mutable", you can update the script and transfer editor permissions.

Update Deployment Script

Command: acurast deployments update script <deployment-id> <script-ipfs> [options]

Arguments:

• <deployment-id>: The deployment ID in format "origin:address:number" (e.g., "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456")
• <script-ipfs>: IPFS hash of the new script (e.g., "ipfs://QmNewScriptHash")

Options:

• --dry-run: Preview the update without applying
• --force: Skip confirmation prompts

Examples:

# Update script (dry run)
acurast deployments update script "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456" "ipfs://QmNewScriptHash" --dry-run

# Update script (actual)
acurast deployments update script "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456" "ipfs://QmNewScriptHash"

Requirements:

• The deployment must have "mutability": "Mutable"
• You must be the current editor of the deployment
• The script must be uploaded to IPFS and provided as an IPFS hash

Transfer Editor Permissions

Command: acurast deployments update editor <deployment-id> <new-editor-address> [options]

Arguments:

• <deployment-id>: The deployment ID in format "origin:address:number" (e.g., "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456")
• <new-editor-address>: The AccountId32 address of the new editor

Options:

• --dry-run: Preview the transfer without executing
• --force: Skip confirmation prompts

Examples:

# Transfer editor permissions (dry run)
acurast deployments update editor "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456" "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL" --dry-run

# Transfer editor permissions (actual)
acurast deployments update editor "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456" "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL"

Requirements:

• The deployment must have "mutability": "Mutable"
• You must be the current editor of the deployment
• The new editor address must be a valid AccountId32 format

Deployment ID Format

The deployment ID is a unique identifier for each deployment on the Acurast platform. It follows the format:

"origin:address:number"

Components:

• origin: The chain name where the deployment was created
  • Currently only "Acurast" is supported
  • This is case-sensitive
• address: The AccountId32 address of the original deployer
  • Must be a valid Substrate AccountId32 format (e.g., 5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL)
  • This is the address that deployed the job initially
• number: The deployment number (u128)
  • This is a sequential number assigned by the blockchain
  • Must be a positive integer

Examples:

# Valid deployment IDs
"Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456"
"Acurast:5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY:1"
"Acurast:5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty:999999"

# Invalid deployment IDs
"Acurast:invalid-address:123"  # Invalid address format
"acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123"  # Wrong case
"Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:-1"  # Negative number

Usage:

• All deployment operations require the full deployment ID format: "origin:address:number"
• Configuration (reuseKeysFrom): You must use the full format as an array

Finding your deployment ID:

• Run acurast deployments ls to see all your deployments
• The deployment ID will be displayed in the list
• For advanced operations, use the full format shown in the list

Validation and Error Handling

The CLI provides comprehensive validation for all deployment management commands:

• Deployment ID validation: Ensures proper format and valid components
• Address validation: Verifies AccountId32 format for all addresses
• IPFS hash validation: Ensures scripts are provided as valid IPFS hashes
• Permission validation: Checks that you have the necessary permissions
• Mutability validation: Ensures the deployment is mutable before allowing updates

Safety Features

• Dry-run mode: Preview changes before applying them
• Confirmation prompts: Require explicit confirmation for destructive operations
• Error messages: Clear, descriptive error messages for validation failures
• Transaction feedback: Display transaction hashes for successful operations

Deployment Features

Mutability

The mutability field controls whether a deployment can be modified after it has been created:

• "Immutable" (default): The deployment cannot be modified after creation. This is the recommended setting for production deployments as it ensures consistency and prevents harmful changes.

• "Mutable": The deployment can be modified after creation. This is an advanced feature and should only be used with careful consideration because misuse could result in harmful updates.

Key Reuse

The reuseKeysFrom field allows you to reuse keys from a previous deployment. This is useful when you want to maintain the same cryptographic keys across deployments. To use this, the referenced deployment has to be "Mutable".

Format: [MultiOrigin, string, number]

• First element: The origin chain (currently only "Acurast" is supported)
• Second element: The address of the original deployer (AccountId32 format)
• Third element: The deployment ID (u128 number)

Example:

{
  "reuseKeysFrom": [
    "Acurast",
    "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
    123456
  ]
}

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.