Spheron Cloud CLI

The Spheron Cloud CLI is a Command Line Interface tool to use the Spheron Cloud Plaform services through CLI.

Installation

For Mac and Linux

To install the Spheron Cloud CLI, run the following command in your terminal:

sudo npm install -g @spheron/cli

For Windows

To install the Spheron Cloud CLI, open your terminal as administrator mode and run the following command:

npm install -g @spheron/cli

Help

The --help argument allows you to get more details about Spheron Cloud CLI commands.

spheron --help

Here is an example of how the result will look:

Spheron CLI 2.0.3
 
spheron [command]
 
Commands:
  spheron login                Log in to your Spheron account — Enter your credentials when prompted.
  spheron logout               Log out of your account — Ends your current session.
  spheron create-organization  Create a new organization — Follow the prompts to specify organization.
  spheron switch-organization  Switch your active organization — Select from available organizations when prompted.
  spheron init                 Initialize deployment configuration — Creates a Spheron configuration file in your project directory.
  spheron deploy               Deploy your instance — Uses the spheron.yaml file to launch your instance.
  spheron build                Build and push Docker image — Compiles an image from spheron.yaml and uploads it to Docker Hub.
  spheron update               Update instance settings — Modifies configuration based on spheron.yaml.
  spheron close                Terminate the instance — Shuts down the specified active instance.
  spheron marketplace-apps     List all marketplace apps — Displays available apps in the Spheron marketplace.
  spheron instances            List project instances — Displays all instances within a specified project.
  spheron instance             Fetch instance and service details — Provides information on an instance and its associated services.
  spheron service              Get service details within an instance — Shows information for services in a specific instance.
  spheron plans                List available plans — Displays all plans offered by Spheron.
  spheron regions              Show available regions — Displays all regions where services can be deployed.
  spheron projects             Retrieve project and instance information — Shows details of the project along with its instances.
  spheron logs                 Fetch service logs — Retrieves all logs for a specific service within an instance.
 
Options:
  --help     Show help                                                             [boolean]
  --version  Show version number                                                   [boolean]

With Commands

spheron [command] --help
# example
spheron login --help

Here is how the result of the above example will look:

Spheron CLI 2.0.3
 
Usage: spheron login [--github|--gitlab|--bitbucket|--token]
 
Options:
  --github     Log in using Github credentials.
  --gitlab     Log in using Gitlab credentials.
  --bitbucket  Log in using Bitbucket credentials.
  --token      Log in by copying the api token from the platform.
  --help       Show help                             [boolean]

Authentication

spheron login

The spheron login command allows you to connect to your Spheron account.

Usage

spheron login

Upon running this command, a prompter will appear that will allow you to select the provider that you want to use for login. Here is how it will look:

Spheron CLI 2.0.3
 
? Select login method: (Use arrow keys)
❯ Github 
  Gitlab 
  Bitbucket

Extended Usage

You can use the following command if you want to connect to your Spheron account without prompter:

GitHub

The --github argument can be used to initiate GitHub OAuth login.

spheron login --github

GitLab

The --gitlab argument can be used to initiate GitLab OAuth login.

spheron login --gitlab

Bitbucket

The --bitbucket argument can be used to initiate Bitbucket OAuth login.

spheron login --bitbucket

Spheron Marktplace App

The spheron marketplace-apps command is used to display a list of available "apps" in the Spheron Marketplace that can be easily deployed on the Spheron platform.

Usage

spheron marketplace-apps

After running the command you will see list of marketplace-apps. These apps are organized by categories like Node, Database, Tools, and AI, making it simple for users to find what they need based on their project requirements. By default, this command will show all the available apps with their respective details such as app ID, name, category, image URL, and documentation link.

Spheron CLI 2.0.0
 
Explore our diverse range of marketplace apps, tailored for seamless deployment on Spheron 🚀
 
APP ID                   NAME              CATEGORY    IMAGE                                  DOCS
6542aeeda299a7af98c8c694 Chia Blockchain   Node        ghcr.io/chia-network/chia:latest       https://docs.chia.net/
654e0ce63ce7371b6ce84c6f AR.IO. Observer   Tools       ghcr.io/ar-io/ar-io-observer:latest    https://ar.io/docs/
 
Helpful Commands:
 
To retrieve the list of marketplace apps within a specific category, use the following command: 
spheron marketplace-apps --category [Node, Database, Tools, AI]

Extended Usage

You can use the following command if you want to retrieve the list of marketplace apps within a specific category:

spheron marketplace-apps --category [Node, Database, Tools, AI]

Here is an example of how the result will look:

spheron marketplace-apps --category Node

Spheron CLI 2.0.0
 
Explore our diverse range of marketplace apps for category <Category Name>, tailored for seamless deployment on Spheron 🚀
 
APP ID                     NAME                 CATEGORY    IMAGE                            DOCS
66210ab04a41a48538c119b2   Eigen Avs Oprator    Node        spheronnetwork/eigen-operator    https://docs.eigenlayer.xyz/
65d6254478d558e1f1015d45   Avail Light Client   Node        spheronnetwork/avail-light       https://docs.availproject.org/category/run-a-validator-node/
 
Helpful Commands:
 
To retrieve comprehensive list of all the marketplace apps, use the following command:

Spheron Instance

The spheron instance command provides an overview of the user's existing deployments or instances on the Spheron platform.

Usage

spheron instance

After running the command you will see essential information including the instance ID, plan usage costs, project name, current status, deployment type, updated time, and creation date. This allows users to quickly monitor and manage their deployments directly from the command line interface (CLI).

Spheron CLI 2.0.0
 
Here are all your instances that you have deployed 🚀
 
INSTANCE ID                PLAN USAGE     PROJECT NAME       STATUS       TYPE        UPDATED AT                 CREATED AT
6542aeeda299a7af98c8c694   $24.23 / mo    my_first_project   ✅ Active    On Demand   2023-12-20T09:57:17.485Z   2023-12-20T09:57:17.485Z
654e0ce63ce7371b6ce84c6f   $322.22 / mo   my_first_project   ✅ Active    Spot        2023-12-20T09:57:17.485Z   2023-12-20T09:57:17.485Z
654e0ce63ce7371b6ce84c6f   $10 / mo       Custom Project     ❌ Closed    Autoscale   2023-12-20T09:57:17.485Z   2023-12-20T09:57:17.485Z
 
Helpful Commands:
 
To retrieve more detailed information about a specific instance, use this following command:
spheron instance --id <INSTANCE ID>

Note: spheron instances --project <PROJECT ID> should just show all the instances irrespective of it’s status

Extended Usage

1. To retrive detailed information of a instance

You can use the following command if you want to retrieve more detailed information about a specific instance, use this following command:

spheron instance --id <INSTANCE ID>

Here is an example of how the result will look:

spheron instance --id 655f2011da6e5919107705ba

Spheron CLI 2.0.0
 
Here is the detailed view of your Instance <INSTANCE ID>! 👇
 
Name: <NAME>
Status: ✅ Active
Monthly Plan Usage: $10 / mo, $0.05 / hr
Total Spent: $23.33
Region: <REGION>
Compute Type: On Demand
Updated At: <DATE>
Created At: <DATE>
 
Here are all your services that you have deployed in this instance! 🚀
 
SERVICE NAME  PLAN NAME     REPLICAS  IMAGE                        CONNECTION URL                                  PORTS        TYPE
web           Ventus Nano   1         crccheck/hello-world:latest  provider.us-east.spheron.wiki 3000:32575        3003:32621   On Demand
ui            Ventus Large  1         mitra/ui:latest              wdwwdwd.ingress.provider.latitude.spheron.wiki  3000:80 On   Demand
service-1     Custom        3         mongo:latest                 provider.us-east.spheron.wiki                   3000:32575   Autoscale
 
To establish a connection with a specific service that is accessible via the internet, follow these steps:
1. If the external port you have specified is 80, you can establish a connection using the services connection URL.
2. In cases where the port is randomly assigned, connect using the format <CONNECTION URL>:<EXTERNAL PORT>
For e.g. if your connection URL is "provider.us-east.spheron.wiki" and the Port is mapped as 3000:32575.
You can connect to Port 3000 using "http://provider.us-east.spheron.wiki:32575".
 
Helpful Commands:
 
To retrieve more detailed information about a specific service, use this following command:
spheron service --id <SERVICE ID>
 
To update your instance configuration, use this following command:
spheron update --instance <INSTANCE ID> --config <PATH TO CONFIG>

2. To retrive detail view of service

You can use the following command if you want to retrieve more detailed information about your service, use this following command:

spheron service --name web --instance <id>

Here is an example of how the result will look:

spheron service --id 655f2011da6e5919107705ba

Spheron CLI 2.0.0
 
Here is the detailed view of your Service <SERVICE ID>! 👇
 
Name: <NAME>
Image: crccheck/hello-world:latest
Status: ✅ Active
Replicas: 2
Region: <REGION>
Compute Type: On Demand / Autoscale / Spot
 
Plan Name: Ventus Nano
CPU: 1
RAM: 2 GB
Storage: 20 GB
Persistent: 256 GB
Plan Usage: $10 / mo, $0.05 / hr
 
Connection URL: provider.us-east.spheron.wiki
Ports: 3000:32575, 3003:32621
 
Environments:
  SPHERON_INSTANCE_ID=655f2011da6e5919107705ba
  PORT=3020
 
Secrets:
  API_KEY=aasaldjsakldjasdasd
 
Commands:
  sh cargo --config run-docker.toml
 
Arguments:
  --name=missds
  --ulimit=no-scale
 
Health Check:
  Port: 3000
  Path: /status
  Status: ✅ Healty
 
Updated At: <DATE>
Created At: <DATE>
 
To establish a connection with a specific service that is accessible via the internet, follow these steps:
 
1. If the external port you have specified is 80, you can establish a connection using the services connection URL.
2. In cases where the port is randomly assigned, connect using the format <CONNECTION URL>:<EXTERNAL PORT>
For e.g. if your connection URL is "provider.us-east.spheron.wiki" and the Port is mapped as 3000:32575.
You can connect to Port 3000 using "http://provider.us-east.spheron.wiki:32575".
 
Helpful Commands:
 
To retrieve logs of the service, use this following command:
spheron log --service <SERVICE ID>
 
To connect shell of the service, use this following command:
spheron shell --service <SERVICE ID>
 
To view compute metrics of the service, use this following command:
spheron metrics --service <SERVICE ID>

Spheron Plans Command

The spheron plans command is designed to present users with a comprehensive list of supported compute plans offered by Spheron, categorized under various tiers according to their resources and pricing structure.

spheron plans --region <REGION>

Here is an example of how the result will look:

Spheron CLI 2.0.0
 
Here are all the On Demand compute plans that we support at Spheron! �
 
PLAN ID                   PLAN NAME     CPU   RAM    GPU               MONTLY PRICING   HOURLY PRICING
 
6542aeeda299a7af98c8c694  Terra Small   2     4 Gb   Nvidia RTX 3090   $300 / mo        $0.3 / hr
654e0ce63ce7371b6ce84c6f  Ventus Large  8     16 Gb  Nvidia A4000      $800 / mo        $0.78 / hr
654e0ce63ce7371b6ce84c6f  Ventus Pico   0.25  2 Gb   N.A               $5 / mo          $0.003 / hr
 
To know more about each plan, please visit our documentation - https://docs.spheron.network/compute/plans/compute-plans/

Spheron Region Command

The spheron regions command offers a concise yet informative presentation of the geographical locations where Spheron supports services.

spheron regions

Here is an example of how the result will look:

Spheron CLI 2.0.0
 
Here are all the regions that we support! 🚀
 
REGIONS
us-east
us-west
us-central
eu-east
eu-west
 
Should you choose not to designate a specific region for your server deployment, selecting the "any" option is available.
This option allows the system to autonomously select a region that has sufficient compute capacity to effectively manage your workload.

Spheron Organizations Command

The spheron organizations command serves to provide a succinct overview of the distinct organization accounts linked to the authenticated user profile. Upon executing the command spheron organizations -get all, the CLI tool retrieves details on all the organizations owned by the currently logged-in user, presenting them in an easy-to-read tabular format.

spheron organizations - get all

Here is an example of how the result will look:

Spheron CLI 2.0.0
 
Checkout all the organisation that you have 🚀
 
ORGANIZATION ID            NAME              COMPUTE PROJECTS   BUCKETS   SITE PROJECTS
6542aeeda299a7af98c8c694   Chia Blockchain   10                 5         0
654e0ce63ce7371b6ce84c6f   AR.IO. Observer   10                 0         2

Spheron Project Command

The spheron projects command lists all the projects in the selected organization. With the '-get all' argument, it shows important info about each project, such as its Project ID, name, total instances, provisioned instances, closed instances, and failed instances.

spheron projects - get all

Here is an example of how the result will look:

Spheron CLI 2.0.0
 
Checkout all the projects in your selected organization <ORG NAME> 🚀
 
PROJECT ID                 NAME               INSTANCES  PROVISIONED  CLOSED  FAILED
6542aeeda299a7af98c8c694   Chia Blockchain    10         5            0       2
654e0ce63ce7371b6ce84c6f   AR.IO. Observer    10         0            2       5
 
Helpful Commands:
 
To retrieve all the instances in your project, use this following command:
spheron instances --project <PROJECT ID>

Spheron Logs Command

The spheron logs command enables users to fetch and view the logs generated by their instances, services, or containers deployed on Spheron.

Note: log type will be optional, if not present, default to instance call

spheron logs --instance <INSTANCE ID> --type <LOG TYPE>

Here is an example of how the result will look:

Spheron CLI 2.0.0
 
Streaming the logs for your instance <INSTANCE ID>! ☁️
 
Starting Deployment Creation Process
Preparing Organization Info
Provisioning Funds For Deployment.
...
 
Helpful Commands:
 
To stream new logs continuously from the service, use this following command:
spheron log --service <SERVICE ID> --type <LOG TYPE> --follow
 
To view only the most recent 'n' logs of the service, use this following command:
spheron log --service <SERVICE ID> --type <LOG TYPE> --tail n

Log have the following options:

--follow - This will continue streaming the new logs from the container (polling)
--tail 100 - Will only show last 100 lines in the log

Also users can follow same syntac do the same for spheron logs --instance <ID> --service <Name>.

E.g. spheron logs --service <SERVICE ID>

Spheron Shell Command

The spheron shell command establishes an interactive shell session as SSH to user instance.

spheron shell --instance <INSTANCE ID> --service <SERVICE NAME>

Here is an example of how the result will look:

Spheron CLI 2.0.0
 
Welcome to Spheron Shell! ☁️
You're now connected just as ssh to your instance.
 
> ls

Spheron Metrics Command

The spheron metrics command provides users with a quick compute resource consumption metric for a specific service hosted on Spheron.

spheron metrics --instance <INSTANCE ID> --service <SERVICE NAME>

Here is an example of how the result will look:

Spheron CLI 2.0.0
 
Here is the compute metric usage of your service! 👇
 
CPU: 0.23 / 4 CPU
RAM: 1.22 GB / 8 GB
 
To access a detailed view of your compute metrics, please navigate to your service on the Spheron App using the following URL:
https://app.spheron.network/compute/<project-id>/<service-id>/metrics.

Spheron init Command

The spheron init command is responsible for initializing and configuring the core components needed to facilitate communication between the developer's local machine and the Spheron platform.

spheron init --import <DOCKER_COMPOSE_PATH/DOCKERFILE> --marketplace <APP_ID>

Here is an example of how the result will look:

Spheron CLI 1.0.16
 
Spheron file already exists, overriding it ⚠️
 
✓ Success! [./docker-compose.yaml / ./Dockerfile] imported successfully!
✓ Success! marketplace app added successfully!
✓ Success! spheron.yaml file created/updated successfully 🚀
Done 10.0s.
 
Note: All the services has been added to your spheron.yaml files.
 
Helpful Commands:
 
To build an instance that exists locally, first add the image name to the spheron.yml file, and then use this following command:
spheron build -u [DOCKERHUB USERNAME] -p [DOCKERHUB PASSWORD]
 
To deploy your instance to Spheron, use this following command:
spheron deploy

Spheron Deploy Command

The spheron deploy command initiates the automated deployment process of a user's configured instance(s) to the Spheron Platform.

spheron deploy

Here is an example of how the result will look:

Spheron CLI 1.0.16
 
Initiating the deployment process of your instance to Spheron...
 
Reading configuration from ./spheron.yaml
 
⠴ Deploying new instance on project <PROJECT NAME> 🚀
 
✓ Success! you instance <INSTANCE ID> is now live on Spheron 🚀
Done 10.0s.
 
Helpful Commands:
 
To retrieve information about the instance, use this following command:
spheron instance --id <INSTANCE ID>

Spheron Update Instance Command

The spheron update --instance <INSTANCE ID> command is used to modify the configuration settings of an existing instance on Spheron. This command reads the updated configuration details from the spheron.yaml file stored locally and applies those changes to the specified instance.

spheron update --instance 65840939e058e2ac5451a6dd

Here is an example of how the result will look:

Spheron CLI 1.0.16
 
Reading from ./spheron.yaml
Initiating the process to update the configuration of your instance in Spheron...
 
✓ Success! Update of instance <INSTANCE ID> is successful! 🚀
Done 10.0s.
 
Helpful Commands:
 
To retrieve more detailed information about the instance, use this following command:
spheron instance --id <INSTANCE ID>

Spheron Close Instance Command

The spheron close --instance <INSTANCE ID> command is used to shut down or terminate an active instance on Spheron.

spheron close --instance 65840939e058e2ac5451a6dd

Here is an example of how the result will look:

Spheron CLI 1.0.16
 
Do you want to close your instance <INSTANCE ID>?
> Yes
  No
 
Initiating the process to close your instance in Spheron...
 
✓ Success! Instance <INSTANCE ID> is successful closed! 🚀
Done 10.0s.
 
Helpful Commands:
 
To deploy a new instance to Spheron, use this following command:
spheron deploy

Spheron Docker Hub Command

The spheron build --dockerhub -u <username> -p <password> command performs a Docker build using a Dockerfile.

spheron build --dockerhub -u <username> -p <pass>

Here is an example of how the result will look:

Spheron CLI 1.0.16
 
✓ Success! Dockerhub login with user <USERNAME> is successful! 🚀
 
Stating build process...
Reading configuration from ./spheron.yaml
 
[app]: Starting docker build.
[app]: #1 [internal] load build definition from Dockerfile
[app]: #1 transferring dockerfile: 31B done
[app]: #1 DONE 0.0s
[app]: #2 [internal] load .dockerignore
[app]: #2 transferring context: 2B done
[app]: #2 DONE 0.0s
[app]: #3 [internal] load metadata for docker.io/library/alpine:3.12
[app]: #4 [auth] library/alpine:pull token for registry-1.docker.io
[app]: #4 DONE 0.0s
[app]: #3 [internal] load metadata for docker.io/library/alpine:3.12
[app]: #3 DONE 1.7s
[app]: #5 [1/3] FROM docker.io/library/alpine:3.12@sha256:c75ac27b49326926b803b9ed43bf088bc220d22556de1bc5f72d742c91398f69
[app]: #5 DONE 0.0s
[app]: #6 [internal] load build context
[app]: #6 transferring context: 35B done
[app]: #6 DONE 0.0s
[app]: #7 [2/3] RUN apk add --no-cache bc
[app]: #7 CACHED
[app]: #8 [3/3] COPY ./entrypoint.sh /
[app]: #8 CACHED
[app]: #9 exporting to image
[app]: #9 exporting layers done
[app]: #9 writing image sha256:3ef7acb19a2b2653c542458da2a4abb9f05aa784732e292222f8b6be407c1ead done
[app]: #9 naming to docker.io/ilija444/app:latest done
[app]: #9 DONE 0.0s
[app]: Use 'docker scan' to run Snyk tests against images to find vulnerabilities and learn how to fix them
[app]: Docker build process completed successfully.
 
[app]: Pushing docker image.
[app]: The push refers to repository [docker.io/ilija444/app]
[app]: a718c0e169b9: Preparing
[app]: 3ca56c20b221: Preparing
[app]: d80e0208345a: Preparing
[app]: 3ca56c20b221: Layer already exists
[app]: d80e0208345a: Layer already exists
[app]: a718c0e169b9: Layer already exists
[app]: latest: digest: sha256:5efaa3cbed885fbfef3efedfd3caacc54a9d7326e3ad1a1185f91cdfc11a5570 size: 945
[app]: Docker push process completed successfully.
 
✓ Successfully build [app] service and pushed to [ilija444/app:latest]! 🚀
Done 10.0s.
 
Helpful Commands:
 
To deploy your instance to Spheron, use this following command:
spheron deploy

Spheron Switch Organization Command

The spheron switch organization command is used to change the active organization context in the Spheron Cloud CLI. It allows users to toggle between different organizations under Spheron platform, ensuring that future commands will operate under the selected organization.

switch org should prompt list of orgs and option to pick one.

spheron switch-organization

Here is an example of how the result will look:

Spheron CLI 2.0.3
 
? Select your organization: (Use arrow keys)
❯ Team 1  
  Team 2

Spheron Cloud API Spheron Cloud SDK