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
Homebrew (macOS)
pipx (isolated)
For Python 3 specifically: pip3 install aiven-client
brew install aiven-client
Install in an isolated environment using pipx: pipx install aiven-client
Verify installation Check that the CLI is installed correctly:
Authentication Authenticate with Aiven using your email and password or a personal token.
Password
Token (recommended)
Marketplace
Enter password
Enter your password when prompted
Create a token
Generate a token from the Aiven Console under User Profile > Tokens
Login with token
Paste your token when prompted If you registered through AWS or GCP marketplace, include the --tenant flag: Or for GCP: Getting started After authentication, you can start managing your Aiven resources.
List projects Set default project avn project switch PROJECT_NAME
List services 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
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:
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:
avn service cli my-postgres
Configuration Get JSON output for any command:
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:
View detailed service type information with all configuration options:
List available plans for a service type:
avn service plans --service-type pg --cloud google-europe-north1
List available cloud regions:
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
# 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
# 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 Enable debug output avN_DEBUG = 1 avn service list
Re-authenticate 