Aiven CLI

Use the Aiven command-line interface to manage services through scriptable commands and automation.

The Aiven command-line interface (CLI) enables you to manage Aiven services and platform resources through terminal commands. The CLI uses the Aiven API and is ideal for scripting, automation, and rapid development workflows.

Installation

The Aiven CLI (avn) is distributed as a Python package and can be installed using pip or Homebrew.

pip

pip install aiven-client

For Python 3 specifically:

pip3 install aiven-client

Homebrew (macOS)

brew install aiven-client

pipx (isolated)

Install in an isolated environment using pipx:

pipx install aiven-client

Verify installation

Check that the CLI is installed correctly:

avn --version

Authentication

Authenticate with Aiven using your email and password or a personal token.

Password

1. Login with email

   avn user login [e-mail]
   
2. Enter password

   Enter your password when prompted

Token (recommended)

1. Create a token

   Generate a token from the Aiven Console under User Profile > Tokens

2. Login with token

   avn user login [e-mail] --token
   

   Paste your token when prompted

Marketplace

If you registered through AWS or GCP marketplace, include the --tenant flag:

avn user login [e-mail] --tenant aws

Or for GCP:

avn user login [e-mail] --tenant google

Getting started

After authentication, you can start managing your Aiven resources.

List projects

avn project list

Set default project

avn project switch PROJECT_NAME

List services

avn service list

Common operations

Service management

Create a service

Create a PostgreSQL service:

avn service create my-postgres \
  --service-type pg \
  --cloud google-europe-north1 \
  --plan startup-4

Create a Kafka service with custom configuration:

avn service create my-kafka \
  --service-type kafka \
  --cloud aws-us-east-1 \
  --plan business-4 \
  -c kafka_connect=true \
  --disk-space-gib 600

Get service details

avn service get my-postgres

Get specific fields in custom format:

avn service get my-postgres --format '{service_name} {service_uri}'

Get output in JSON:

avn service get my-postgres --json

Update a service

Scale to a different plan:

avn service update my-postgres --plan business-4

Move to a different cloud region:

avn service update my-postgres --cloud azure-germany-north

Update configuration:

avn service update my-postgres -c ip_filter=10.0.1.0/24,10.25.10.1/32

Power management

Power off a service (stops billing for compute):

avn service update my-postgres --power-off

Power on a service:

avn service update my-postgres --power-on

Delete a service

This permanently deletes the service and all data. This action cannot be undone.

avn service terminate my-postgres

Force deletion without confirmation:

avn service terminate my-postgres --force

Wait for service to be ready

avn service wait my-postgres

Database operations

PostgreSQL and MySQL databases

List databases:

avn service database-list my-postgres

Create a database:

avn service database-create my-postgres mydb

Delete a database:

avn service database-delete my-postgres mydb

User management

List service users:

avn service user-list my-postgres

Create a new user:

avn service user-create my-postgres newuser

Reset user password:

avn service user-password-reset my-postgres myuser

Delete a user:

avn service user-delete my-postgres olduser

Apache Kafka operations

Topic management

List topics:

avn service topic-list my-kafka

Create a topic:

avn service topic-create my-kafka \
  my-topic \
  --partitions 3 \
  --replication 2 \
  --retention 72h

Update topic configuration:

avn service topic-update my-kafka my-topic \
  --retention 168h \
  --min-insync-replicas 2

Delete a topic:

avn service topic-delete my-kafka my-topic

ACL management

List ACLs:

avn service acl-list my-kafka

Add an ACL entry:

avn service acl-add my-kafka \
  --permission read \
  --topic my-topic \
  --username myuser

Delete an ACL:

avn service acl-delete my-kafka ACL_ID

Connection information

Get connection details:

avn service connection-info my-postgres

Get specific connection format:

avn service connection-info my-kafka --format prometheus

Service integrations

List available integration types:

avn service integration-types-list

Create an integration:

avn service integration-create \
  --integration-type datadog \
  --source-service my-postgres \
  --dest-endpoint my-datadog-endpoint

List integrations:

avn service integration-list my-postgres

Advanced features

VPC management

List VPCs:

avn vpc list

Create a VPC:

avn vpc create \
  --cloud aws-us-east-1 \
  --network-cidr 10.0.0.0/24

Create a VPC peering connection:

avn vpc peering-connection create \
  --project-vpc-id VPC_ID \
  --peer-cloud-account 123456789012 \
  --peer-vpc vpc-abcdef123456

Service logs

View service logs:

avn service logs my-postgres

Follow logs in real-time:

avn service logs my-postgres --follow

Metrics

Get service metrics:

avn service metrics my-postgres --period day

Available periods: hour, day, week, month, year

Query statistics

List slow queries (PostgreSQL/MySQL):

avn service queries my-postgres

Reset query statistics:

avn service queries-reset my-postgres

Maintenance

Start maintenance immediately:

avn service maintenance-start my-postgres

Interactive shells

Open an interactive shell to a service:

PostgreSQL

avn service cli my-postgres

avn service cli my-redis

Configuration

Output format

Get JSON output for any command:

avn service list --json

Use custom formatting:

avn service list --format '{service_name} {state} {plan}'

Project switching

Switch between projects:

avn project switch my-other-project

Run a single command against a different project:

avn service list --project my-other-project

Configuration file

The CLI stores configuration in ~/.config/aiven/aiven-credentials.json

Service types and plans

List available service types:

avn service types

View detailed service type information with all configuration options:

avn service types -v

List available plans for a service type:

avn service plans --service-type pg --cloud google-europe-north1

List available cloud regions:

avn cloud list

Scripting tips

Error handling

if avn service get my-service &> /dev/null; then
  echo "Service exists"
else
  echo "Service does not exist"
fi

Parse JSON output

# Using jq
avn service get my-postgres --json | jq -r '.service_uri'

# Get service state
STATE=$(avn service get my-postgres --json | jq -r '.state')

Wait for service creation

avn service create my-postgres \
  --service-type pg \
  --cloud google-europe-north1 \
  --plan startup-4

# Wait for it to be running
avn service wait my-postgres

echo "Service is ready!"

Bulk operations

# Create multiple databases
for db in db1 db2 db3; do
  avn service database-create my-postgres $db
done

# List all services across all projects
for project in $(avn project list --json | jq -r '.[]'); do
  echo "Project: $project"
  avn service list --project $project
done

Common use cases

CI/CD integration

# Create test database
avn service create test-db-$CI_BUILD_ID \
  --service-type pg \
  --cloud google-europe-north1 \
  --plan hobbyist

# Wait for it to be ready
avn service wait test-db-$CI_BUILD_ID

# Get connection URI
DB_URI=$(avn service get test-db-$CI_BUILD_ID --json | jq -r '.service_uri')

# Run tests
pytest --db-uri=$DB_URI

# Clean up
avn service terminate test-db-$CI_BUILD_ID --force

Backup and disaster recovery

# List available backups
avn service backup-list my-postgres

# Create service from backup
avn service create my-postgres-restore \
  --service-type pg \
  --cloud google-europe-north1 \
  --plan startup-4 \
  -c backup_name=BACKUP_NAME

Migration tasks

# Check migration from external database
avn service task-create \
  --operation migration_check \
  --source-service-uri mysql://user:pass@host:port/db \
  --project myproject \
  mysql-service

# Get task status
avn service task-get \
  --task-id TASK_ID \
  --project myproject \
  mysql-service

Troubleshooting

Check CLI version

avn --version

Enable debug output

avN_DEBUG=1 avn service list

Re-authenticate

avn user logout
avn user login [e-mail] --token

Related resources

• Aiven CLI GitHub Repository
• Getting Started Tutorial (Video)
• Aiven CLI Blog Post
• Aiven API Documentation