How to connect to Hyperlift using Hyperlift CLI

Hyperlift CLI is a command-line tool for managing Hyperlift applications on the Spaceship platform via the terminal. 

The tool is open source here. It talks to the Spaceship External API and authenticates with an API key and secret. With its help, you can do the following:

• View and manage the application;

• Build, start, stop, and restart the application;

• View runtime and build logs;

• View application metrics;

• Manage environment variables;

• Use JSON output for scripting and automation;

• Keep the CLI up to date.

The CLI communicates with the Spaceship External API and uses a Spaceship API key and secret for authentication. Therefore, internal and administrative information is kept hidden, since the CLI accesses internal services directly.

In this article, we will cover:

1. How to install the Hyperlift CLI;

2. How to create API credentials;

3. How to log in to the CLI;

4. How to manage Hyperlift application via CLI;

5. How to view logs and metrics;

6. How to manage environment variables;

7. How to update the CLI.

1. Install the Hyperlift CLI

The Hyperlift CLI can be installed on macOS, Windows, and Linux. Depending on your OS, run the installation command. The script automatically detects your operating system and architecture, downloads the appropriate release, verifies it, and installs the hyperlift command.

macOS

If you use Homebrew, run:

brew install nccloud/tap/hyperlift

Windows

If you use Scoop, run:

scoop bucket add nccloud https://github.com/NCCloud/scoop-bucket

scoop install hyperlift

Linux or macOS

You can also use the installation script:

curl -fsSL https://raw.githubusercontent.com/NCCloud/hyperlift-cli/main/scripts/install.sh | sh

Manual installation

Alternatively, download the archive for your operating system from the Hyperlift CLI Releases page, extract it, and add the hyperliftexecutable to your system's PATH.

2. Create API credentials

The Hyperlift CLI uses a Spaceship API key and secret to authenticate your requests.

To create API credentials:

1. Log in to your Spaceship account.

2. Open API Manager.

3. Click on the + New API key button to create a new key:
   
   

   

   
   

4. Name the key and select the permissions required for the actions you want to perform:
   
   

   

   
   

5. If you select the Custom access level, there are three access options for Hyperlift:
   

   

A key with only the Read scope is sufficient if you only need to view your applications, logs, or metrics. Additional scopes are required for application management and environment variables.

6. Copy the created API key and the secret, and save the details.

Important: The API secret is displayed only once when you create the credentials. Make sure to save it securely.

Click Done:

7. The created key will be listed under the API Manager menu:

3. Log in to the Hyperlift CLI

After installing the CLI and creating your API credentials, run:

hyperlift auth login

The CLI will ask you to enter your API key and secret.

After successful authentication, the API key is stored in the Hyperlift configuration file, while the API secret is stored securely in your operating system's keyring when available.

To check your login status, run:

hyperlift auth whoami

To log out and remove your stored credentials, run:

hyperlift auth logout

Tip: If you receive a "Not logged in" message, run hyperlift auth login again. If you receive a 403 error, your API key may be missing the required scope. 

Non-interactive authentication

If you need to authenticate from a script, you can provide the credentials using command-line options:

hyperlift auth login --key "$KEY" --secret "$SECRET"

However, using --secret exposes the secret as a command-line argument. For better security, you can pass the secret through standard input:

printf '%s' "$SECRET" | hyperlift auth login --key "$KEY" --with-stdin

4. Basic commands to manage a Hyperlift application

Use the apps commands to view and manage your Hyperlift applications.

View applications

Use the appscommands to view and manage your Hyperlift applications.

Build an application

To start building an application, run:

hyperlift apps build <app-id>

By default, the command returns after the API accepts the build request.

If you want the CLI to wait until the build is completed, add the --wait option:

hyperlift apps build <app-id> --wait

You can also specify how long the CLI should wait:

hyperlift apps build <app-id> --wait --timeout 15m

The default timeout is 10 minutes.

Start, stop, or restart an application

Use the following commands to manage the application status:

By default, these commands return after the API accepts the request. Add --wait if you want the CLI to wait until the operation is completed.

For example:

hyperlift apps restart <app-id> --wait

View application logs

You can use the logs command to view both runtime and build logs.

Note: The --follow option periodically checks for new log entries. It does not establish a live streaming connection.

View application metrics

Use the metrics command to monitor your application's resource usage. The available metrics include:

• Memory usage;

• CPU usage;

• Network receive rate;

• Network transmit rate;

• Ephemeral storage usage;

• Persistent storage usage.

Manage environment variables

You can use the envcommands to view, add, update, and remove environment variables.

Important: Updating environment variables restarts the application. Wait until the application is running again before making another environment variable change.

Hyperlift uses the APPLICATION_PORT environment variable to determine the port on which the application is available. Its default value is 8080.

Customize command output 

By default, Hyperlift CLI commands display information in a human-readable format.

If you need to use the output in scripts or other tools, you can use the following options.

Note: The --json and --quiet options cannot be used together.

Update the Hyperlift CLI

Get help per command

Each Hyperlift CLI command has its own help information.

The help output includes the available options and arguments for the selected command.

For the latest command list and technical details, refer to the Hyperlift CLI repository.