May 30, 2019
Using traditional Unix tools with the Aiven CLI
Got bash, grep, cat and wc and want the the simplest commands to select, run and administer your Aiven services? Learn how.
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 thejq
tool to extract data in a more powerful way than withgrep
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 withavn
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!
Subscribe to the Aiven newsletter
All things open source, plus our product updates and news in a monthly newsletter.
Related resources
Dec 7, 2021
Aiven's OSPO is dealing with migration of Apache Kafka to Scala 3. Find out how they managed!