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

A cli to interact with the Acurast Cloud
https://github.com/acurast/acurast-cli

acurast cli cloud network

Last synced: 6 months ago
JSON representation

A cli to interact with the Acurast Cloud

• Host: GitHub
• URL: https://github.com/acurast/acurast-cli
• Owner: Acurast
• Created: 2024-06-20T10:16:42.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2025-11-12T09:07:34.000Z (7 months ago)
• Last Synced: 2025-11-12T11:17:59.697Z (7 months ago)
• Topics: acurast, cli, cloud, network
• Language: TypeScript
• Homepage: https://acurast.com
• Size: 814 KB
• Stars: 55
• Watchers: 4
• Forks: 14
• Open Issues: 11
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          


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:

```bash

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 ` - 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 ` - View details of a specific deployment.

  - `deployments  --update-env-vars` - Update environment variables for a deployment.

  - `deployments --cleanup` - Clean up old, finished deployments.

  - `deployments  --cleanup` - Clean up a specific deployment.

  - `deployments update script   [options]` - Update the script of a mutable deployment.

  - `deployments update editor   [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:

```json

{

  "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](https://faucet.acurast.com).

`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](https://pinata.cloud/) 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:

```text

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.

```json

{

  "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:

```typescript

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

```bash

# 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   [options]`

**Arguments**:

- ``: The deployment ID in format `"origin:address:number"` (e.g., `"Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456"`)

- ``: IPFS hash of the new script (e.g., `"ipfs://QmNewScriptHash"`)

**Options**:

- `--dry-run`: Preview the update without applying

- `--force`: Skip confirmation prompts

**Examples**:

```bash

# 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   [options]`

**Arguments**:

- ``: The deployment ID in format `"origin:address:number"` (e.g., `"Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456"`)

- ``: The AccountId32 address of the new editor

**Options**:

- `--dry-run`: Preview the transfer without executing

- `--force`: Skip confirmation prompts

**Examples**:

```bash

# 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**:

```bash

# 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**:

1. Run `acurast deployments ls` to see all your deployments

2. The deployment ID will be displayed in the list

3. 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**:

```json

{

  "reuseKeysFrom": [

    "Acurast",

    "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",

    123456

  ]

}

```

## Development

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

Clone the repository:

```bash

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

```

Navigate to the project directory:

```bash

cd acurast-cli

```

Install the dependencies:

```bash

npm install

```

After making your changes, you can run tests using:

```bash

npm run test

```

To test your changes locally:

```bash

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.