Koyeb CLI 3.0: Better flows, improved troubleshooting, and reworked foundations

We are happy to announce the release of the Koyeb CLI 3.0! This release brings three crucial improvements: Smoother flow for creating and updating services, reworked error messages to ease troubleshooting, and a new foundation to continue building out our CLI.

If you want to get started using the Koyeb CLI to deploy your services and applications worldwide directly from your terminal, read the Koyeb CLI documentation and CLI reference.

• Smoother service creation and updates
• Easier troubleshooting with reworked error messages
• A stronger foundation for future improvements

Smoother service creation and updates

In the past, using the CLI to create or update a service was not the straightforward process it should be. For example, some parameters were silently ignored and it was not easy to understand how to use the CLI for advanced usages without reading the source code. Now, using the CLI is much more intuitive and reading the --help output provides you with clear guidance to create or edit a service.

For example, here is the new --help output for configuring custom domains on Koyeb using the CLI:

❯ koyeb domains --help
Domains

Usage:
  koyeb domains [command]

Aliases:
  domains, dom, domain

Available Commands:
  attach      Attach a custom domain to an existing app
  create      Create domain
  delete      Delete domain
  describe    Describe domain
  detach      Detach a custom domain from the app it is currently attached to
  get         Get domain
  list        List domains
  refresh     Refresh a custom domain verification status

Flags:
  -h, --help   help for domains

Global Flags:
  -c, --config string   config file (default is $HOME/.koyeb.yaml)
  -d, --debug           enable the debug output
      --debug-full      do not hide sensitive information (tokens) in the debug output
      --force-ascii     only output ascii characters (no unicode emojis)
      --full            do not truncate output
  -o, --output output   output format (yaml,json,table)
      --token string    API token
      --url string      url of the api (default "https://app.koyeb.com")

Use "koyeb domains [command] --help" for more information about a command.

The process to update a service has also been greatly improved. The command koyeb service update myapp/myservice --env NEWENV=VALUE used to erase all of the service's environment variables, and set only one variable NEWENV. With the current release, this command now does what you probably expect: create or update the environment variable NEWENV, and leave the other variables untouched.

Easier troubleshooting with reworked error messages

When deploying your services and applications, you may face errors. Naturally, you will want to collect as much information about the error as possible to troubleshoot the issue quickly.

We reworked the error messages in the Koyeb CLI to add more context and ultimately make it easier for you to troubleshoot issues. Previously, the error messages in our CLI were cryptic and hard to understand. We now provide more information about why the error happened: Was there an API error or an invalid token for instance?

When we can, we also provide suggestions on how to solve the issue: Perhaps you need to wait a few minutes and try the request again, or maybe you need to fix the parameters or provide a valid authentication token.

Example error messages

Here is the error message you would face if your authentication token were invalid:

❯ koyeb app list
❌ Error while listing the applications: your authentication token is invalid or has expired

🏥 How to solve the issue?
Please login again using `koyeb login`, or provide a valid token using the `--token` flag.

In this case, we see that the authentication token is invalid and we can solve the issue by trying to log in again or providing a valid token.

Imagine you are creating a new service called myservice to deploy to an application called staging running on Koyeb. If you have not already created an application called staging, you will see the following error message:

❯ koyeb service create myservice --app staging
❌ Unable to find the application `staging`: no object could be found from the provided identifier

🔎 Additional details
The supported formats to resolve a application are:
* application full UUID
* application short ID (8 characters)
* application name

🏥 How to solve the issue?
Provide a valid application identifier

Here we see that the application staging cannot be found, and that we can solve the issue by providing an application name that exists.

A stronger foundation for future improvements

When we first set out to build our CLI, we moved quickly and it eventually became a challenge to maintain. To remedy this bumpy start, we spent a lot of time refactoring our CLI to ensure the smooth integration of future updates. So heads up: you should expect to see more exciting features pretty soon!

To get started using the Koyeb CLI to deploy your services and applications worldwide directly from your terminal, make sure to update or install the Koyeb CLI and read the CLI reference.

By the way, you can easily contribute to the CLI and we provide free credits for contributions! Check the public list of issues: https://github.com/koyeb/koyeb-cli/issues.

If you want to talk more about the Koyeb CLI or this article, you can reach out to us on Slack, over on the Koyeb Community and on Twitter @brmzkw and @AlisdairBroshar.