Using traditional Unix tools with the Aiven CLI

Things have moved on since 2019, and we've continued improving the Aiven command line tool.
There's a new blog post at Get things done with the Aiven CLI which explains how to get started, and how to manage a PostgreSQL® service from start to finish. It also gives examples of using the --json switch and the jq tool to extract data in a more powerful way than with grep and friends.

You can do most of your Aiven service administration straight from your Aiven Console. However, for those times when you need to run a quick shell command on our CLI (command line interface) to check service status, power on or off services, filter through available plans or clouds, upgrade some of your services or watch for patterns in event logs, this guide is for you.

You can also use these commands for scripting and automation, as a basis for constructing your own commands or aliases, or even to dig deeper into the CLI for more possibilities. In this article, we’ll focus more on grepping through the sometimes rather lengthy and / or verbose avn outputs to find specific information more easily — although there are some admin and service deployment commands included.

While intended for use with our CLI, we also hope you’ll find this as a useful guide to get familiar with — or to revisit -- some basic bash scripting.

Feel free to copy / paste, but remember to adjust to the variables you need, for example your --cloud, and/or your --project setting depending on what you’re trying to do. Other variables may include such items as your login name as well as your chosen project and service instance names. Also, while we've specified writing to files or stdout; or clearing screens for aesthetic purposes, feel free to customize the commands you need.

Our list of commands here isn’t exhaustive but is complementary to the one on the Aiven client’s github profile, with some overlapping on the basic stuff. Be sure to check out both!

Finally, we’ll share the lot on github and include a few keyboard-friendly aliases for useful commands that you can use as a basis for some of your own Aiven service deployment and DevOps infrastructure.

Table of Contents

• Installing the Aiven CLI
• Logging in and logging out
• Viewing clouds, services, regions and plans
• Creating, viewing, powering on or off, and deleting services
• Viewing and filtering event logs
• AVN Help and miscellaneous options
• Creating aliases for regularly used commands
• Wrapping up

Installing the Aiven CLI

You’ll need at least Python 3.7 or newer versions, with pip installed.

python -m pip install aiven-client

See the Aiven Client documentation on Github for instructions for other platforms.

Logging in and logging out

Login a user

NOTE: you’ll be prompted for your password.

avn user login <user@aiven.io>

Note: we now recommend logging in with an access token (using the --token switch) - see Log in to Aiven with avn in the 2022 article.

Find help with user admin

avn user -h

Get session/auth info on all users in your project

avn user info

Logout

avn logout

Viewing clouds, services, regions and plans

List all available services on Aiven

avn service types

List all available clouds

avn cloud list

List all available clouds in the United States

avn cloud list | grep United

List the last 5 clouds alphabetically in the US

avn cloud list | grep United | tail -5

List the first five clouds alphabetically in the US

avn cloud list | grep United | head -5

List the first 20 clouds in the US region

avn cloud list | grep United | head -20

List all clouds available in "California" region.

NOTE: writes a file (ca_clouds)

avn cloud list | grep -E "California" > ca_clouds && cat ca_clouds

Exclude all clouds in Finland and California.

NOTE: writes to a file (not_ca_not_fi_clouds)

avn cloud list | grep -Ev "California|Finland" > not_ca_not_fi_clouds && cat not_ca_not_fi_clouds

Count all clouds in a given region

avn cloud list | grep -E "California" > ca_clouds && wc -l ca_clouds

List clouds in successive alphabetical order by 3 specified regions

regions=('africa' 'australia' 'europe')
for r in "${regions[@]}"
do
    avn cloud list | grep $r
done

List all clouds filtered by a specific cloud provider within two regions

clear && avn cloud list | grep -E 'europe|north america' | grep 'aws-'

Count the total number of available Aiven clouds

avn cloud list | grep -Ev 'CLOUD_DESCRIPTION|=' > clouds_adjusted && wc -l clouds_adjusted

List all clouds, sorted alphabetically by provider

providers=('aws-' 'azure-' 'do-' 'google' 'packet')
for p in "${providers[@]}"
do
  avn cloud list | grep $p
done

List all available plans, given the cloud

avn service plans --cloud do-sfo

List all available hobbyist plans, given the cloud

avn service plans --cloud do-sfo | grep -E 'hobbyist'

List all available kafka plans, given the cloud

avn service plans --cloud do-sfo | grep -E 'kafka:'

List all available postgres and kafka plans within a specified cloud, filtered by CPU constraints

clear && avn service plans --cloud do-sfo | grep -E 'pg:|kafka:' | grep -E '8 CPU|16 CPU'

Count the number of available plans in a specific cloud

avn service plans --cloud do-sfo | grep -E 'cassandra:|opensearch:|grafana:|influxdb:|kafka:|mysql:|pg:|redis:' > plans_on_this_cloud && wc -l plans_on_this_cloud

Count all plans on a specific cloud with cost < $10/hr

avn service plans --cloud do-sfo | grep -Ev '\$\d\d.\d{3}/h' | grep -E 'cassandra:|opensearch:|grafana:|influxdb:|kafka:|mysql:|pg:|redis:' > cheap_plans && wc -l cheap_plans

Make a nicely formatted text file of < $10/hr plans on a specific cloud and display it

avn service plans --cloud do-sfo | grep -Ev '\$\d\d.\d{3}/h' > cheap_plans && cat cheap_plans

List all plans on a specific cloud with cost < $10/hr

clear && avn service plans --cloud do-sfo | grep -Ev '\$\d\d.\d{3}/h' | more

List all plans on a specific cloud with cost > $10/hr

clear && avn service plans --cloud do-sfo | grep -E '\$\d\d.\d{3}/h'

Creating, viewing, powering on / off and deleting services

Create an Postgres service on your default cloud with hobbyist plan

avn service create mypg -t pg --plan hobbyist

Create a Cassandra instance with startup-4 plan

avn service create mycass -t cassandra --plan startup-4

Create a Kafka instance in next higher tier

avn service create mykafka -t kafka --plan business-4

Roll out multiple service instances on multiple tiers

avn service create mycass -t cassandra --plan startup-4 && avn service create mykafka -t kafka --plan business-4

Upgrade an existing service to a higher tier

avn service update mycass --plan startup-8

Upgrade an existing service to a higher tier AND move it to another cloud region

avn service update mycass --plan startup-8 --cloud aws-us-west-1

List all of your available Aiven services

avn service list

Power on multiple services

avn service update myes1 --power-on && avn service update myes2 --power-on

List only services currently running

avn service list | grep POWERON

List only services currently switched off

avn service list | grep POWEROFF

Get only the latest timestamps (CREATE_TIME and UPDATE_TIME) for each currently rebuilding service

This command is useful for troubleshooting a slowly-restarting service.

avn service list | grep REBUILDING | grep -Eo '\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(.\d{6})?((\+\d\d:\d\d)|Z)'

Get the timestamps for your recently switched off services

avn service list | grep POWEROFF | grep -Eo '\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(.\d{6})?((\+\d\d:\d\d)|Z)'

Get the latest timestamps for currently running services

avn service list | grep RUNNING | grep -Eo '\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(.\d{6})?((\+\d\d:\d\d)|Z)'

Power off your service and list services

avn service update myes --power-off && avn service list

Poweroff multiple service instances

services=('mycass' 'mykafka' 'myes')
for s in "${services[@]}"
do
  avn service update $s --power-off
done

Terminate multiple service instances

avn service terminate mycass && avn service terminate mykafka

Viewing and filtering event logs

Show all service events in your project

avn events

Find 5 most recent events

avn events | grep -Ev 'TIME|=' | head -5

Find service maintenance events

avn events | grep -E '_maintenance'

Find service_delete events for your logged in project

avn events | grep -E '_delete'

Count the number of lines in event log

avn events | grep -Ev 'TIME|=' > events && wc -l events

List all events related to powered on / off services

avn events | grep power > power_events && cat power_events

List all events not related to powered up or down services

avn events | grep -Ev power > live_events && cat live_events

AVN help and miscellaneous options

Get general AVN CLI help

avn help

avn -h

Get help on a specific function

avn card -h

avn cloud -h

avn credits -h

avn events -h

avn project -h

avn service -h

avn service create -h

List all credit cards associated with your project

avn card list

List all available credits in your project

avn credits list

List all of your current projects

avn project list

Get project details, including associated credit card, billing address and country code

avn project details

List all vpcs

avn vpc list

Creating aliases for regularly used commands

If you are using a command often, it might be useful to create an alias or a shell function for it. You can add these to .bashrc or to a shell script in your path. Here are some examples:

List clouds in alphabetical order by 3 major regions

show_my_clouds() {
clear
regions=('australia' 'europe' 'north')
for r in "${regions[@]}"
do
    avn cloud list | grep $r
done }

View plans on a specific cloud that cost < $10/hr

get_cheap_plans() {
  clear && avn service plans --cloud do-sfo | grep -Ev '\$\d\d.\d{3}/h' | more
}

Turn on a specific service

alias turnon_service='avn service update myes --power-on'

Turn off a specific service

alias turnoff_service='avn service update myes --power-off'

Get timestamps from all services

alias get_timestamps='avn service list | grep -Eo "\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(.\d{6})?((\+\d\d:\d\d)|Z)"'

Wrapping up

In this piece, we looked at many things you can do with the Aiven command-line interface (CLI) including installation and authentication, viewing clouds, services, regions and plans, working with event logs, getting help, and even creating aliases for frequently-used functions.

We hope that you'll find this not only helpful as a comprehensive primer for Aiven CLI, but also as a general, basic bash reference.

As mentioned before, our CLI is only one of many ways to interact with our globally-available, open source services. Want to try them out? Check out our free 30 day trial. To stay apace with new developments, you can also subscribe to our blog and changelog RSS feeds, or follow us on Twitter or LinkedIn!