Blog

September 30, 2023

Zeabur CLI

Hepeng Lee

Basic Concepts of Zeabur

For a better reading experience, let me introduce you some basic concepts of Zeabur.

Zeabur is a platform that helps developers to deploy painlessly and scale infinitely.

There are 3 levels of application in Zeabur: Project, Service and Deployment.

• Service can be imported from a GitHub repo or a prebuilt image, one service is usually used for one specific task, like a website or a database.
• A project is typically made up of multiple services, which are designed to work together seamlessly to achieve a common goal. These services are often connected to a private network, which can improve communication between them and make it easier to manage the flow of data and information.
• Within each service, there may be many different deployments, each of which is designed to handle a specific version of the service. This allows developers to make changes and updates to the service over time, without disrupting the overall functionality of the project as a whole.

What’s is CLI

The CLI (command-line interface) is a powerful tool that allows users to interact with their operating systems through text-based commands. By leveraging the CLI, users can execute a wide range of functions, from basic tasks like creating and deleting files, to more complex operations like configuring network settings and managing system processes.

It is an essential tool for anyone looking to take control of their operating system and maximize their productivity. While it can be intimidating at first, especially for users who are accustomed to GUIs, the benefits of the CLI are well worth the effort required to learn its ins and outs.

Why We Need CLI

Nowadays, almost all the software applications are designed with a great graphical user interface (GUI) to provide an enhanced user experience. However, it is important to note that the command-line interface (CLI) is still a vital part of many software applications. While the GUI provides a user-friendly approach to interact with software, the CLI offers a powerful way to perform complex tasks with efficiency and flexibility.

Most of Zeabur's users are developers who use terminals daily. Therefore, using CLI to monitor and manage services deployed on Zeabur may be more convenient.

How We Implement CLI

Architecture

For a better develop experience, we use Cobra as our CLI framework.

Zeabur follows the principle of "Dependency Inversion, not Dependency on Implementations", abstracting all functions as interfaces and putting them all into `cmdutil.Factory`. The corresponding implementation is injected into the `Factory` during project initialization, instead of being called directly in the code.

This is the definition of Factory. As you can see, whether it's logging, API calls, or interactions, they are all defined as interfaces.

The benefits of this approach are significant:

• Decoupling of code, making it easy to replace/extend implementations (e.g. replacing the default GraphQL implementation of ApiClient with RESTful)
• Facilitates testing, as it is easy to mock the corresponding implementation
• Facilitates integration into external projects

At the same time, we used mockery to generate corresponding mock implementations, which are convenient for unit testing.

We also wrote a mock implementation specifically for zap (logging) for unit testing. This implementation can output logs to a string array during testing, enabling log comparison level unit testing.

Auth

When it comes to implementing authentication in CLI applications, there are several approaches that can be taken. For example, one approach is to use a third-party authentication provider, which can simplify the process and provide additional security features. Another option is to implement a custom authentication solution, which can be tailored to the specific needs of the application. Additionally, some CLI applications may benefit from integrating with existing authentication systems, such as OAuth or LDAP, which can provide a more seamless user experience.

In our situation, we use OAuth for our auth system in CLI, with https://github.com/cli/oauth. You can use `zeabur auth login` in our CLI, and we it will open your browser with our auth website to request the auth server for a token. After pressing the confirm button, CLI will automatically get your account information in Zeabur.

The principle is as follows: CLI starts an HTTP service in the background, listens on a random port, acts as an OAuth2 client, and then opens a browser to complete the login through Zeabur OAuth Server. We also have a built-in Refresh Token mechanism, which refreshes the token as needed by default after each command ends.

Context

As its is mentioned above, Zeabur has designed the concept of context, which can be specified by using `zeabur context set <project|service|environment>` to set the default context.

Similarly, when setting the context with set, it is possible to select it interactively without having to remember the ID or Name.

We have designed a BasicInfo interface to abstract the corresponding basic information, such as Project, Service, Environment.

Whenever the context is updated, the corresponding information will be stored in the configuration file of Zeabur CLI (`~/.config/zeabur/cli.yaml`).

Release

Zeabur uses GoReleaser for automatic versioning. The CLI is published to Homebrew, Scoop, Install Script, and more by triggering GitHub Action with git tag.

Thanks to our great community, Zeabur CLI now supports `brew install` two days after its initial publication. This feature was made by abdfn's contributions.

Summarize

Zeabur CLI is a command-line interface tool that is currently in the beta stage of development. Your input will help us ensure that Zeabur CLI is the best tool it can be, and we are grateful for any assistance you can provide us with. We welcome all contributions, big or small, and we encourage you to contact us with any questions or feedback you may have.