> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/aiven/aiven-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tabs>
  <Tab title="pip">
    ```bash theme={null}
    pip install aiven-client
    ```

    For Python 3 specifically:

    ```bash theme={null}
    pip3 install aiven-client
    ```
  </Tab>

  <Tab title="Homebrew (macOS)">
    ```bash theme={null}
    brew install aiven-client
    ```
  </Tab>

  <Tab title="pipx (isolated)">
    Install in an isolated environment using pipx:

    ```bash theme={null}
    pipx install aiven-client
    ```
  </Tab>
</Tabs>

### Verify installation

Check that the CLI is installed correctly:

```bash theme={null}
avn --version
```

## Authentication

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

<Tabs>
  <Tab title="Password">
    <Steps>
      <Step title="Login with email">
        ```bash theme={null}
        avn user login YOUR_EMAIL@example.com
        ```
      </Step>

      <Step title="Enter password">
        Enter your password when prompted
      </Step>
    </Steps>
  </Tab>

  <Tab title="Token (recommended)">
    <Steps>
      <Step title="Create a token">
        Generate a token from the [Aiven Console](https://console.aiven.io) under **User Profile** > **Tokens**
      </Step>

      <Step title="Login with token">
        ```bash theme={null}
        avn user login YOUR_EMAIL@example.com --token
        ```

        Paste your token when prompted
      </Step>
    </Steps>
  </Tab>

  <Tab title="Marketplace">
    If you registered through AWS or GCP marketplace, include the `--tenant` flag:

    ```bash theme={null}
    avn user login YOUR_EMAIL@example.com --tenant aws
    ```

    Or for GCP:

    ```bash theme={null}
    avn user login YOUR_EMAIL@example.com --tenant google
    ```
  </Tab>
</Tabs>

## Getting started

After authentication, you can start managing your Aiven resources.

### List projects

```bash theme={null}
avn project list
```

### Set default project

```bash theme={null}
avn project switch PROJECT_NAME
```

### List services

```bash theme={null}
avn service list
```

## Common operations

### Service management

#### Create a service

Create a PostgreSQL service:

```bash theme={null}
avn service create my-postgres \
  --service-type pg \
  --cloud google-europe-north1 \
  --plan startup-4
```

Create a Kafka service with custom configuration:

```bash theme={null}
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

```bash theme={null}
avn service get my-postgres
```

Get specific fields in custom format:

```bash theme={null}
avn service get my-postgres --format '{service_name} {service_uri}'
```

Get output in JSON:

```bash theme={null}
avn service get my-postgres --json
```

#### Update a service

Scale to a different plan:

```bash theme={null}
avn service update my-postgres --plan business-4
```

Move to a different cloud region:

```bash theme={null}
avn service update my-postgres --cloud azure-germany-north
```

Update configuration:

```bash theme={null}
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):

```bash theme={null}
avn service update my-postgres --power-off
```

Power on a service:

```bash theme={null}
avn service update my-postgres --power-on
```

#### Delete a service

<Warning>
  This permanently deletes the service and all data. This action cannot be undone.
</Warning>

```bash theme={null}
avn service terminate my-postgres
```

Force deletion without confirmation:

```bash theme={null}
avn service terminate my-postgres --force
```

#### Wait for service to be ready

```bash theme={null}
avn service wait my-postgres
```

### Database operations

#### PostgreSQL and MySQL databases

List databases:

```bash theme={null}
avn service database-list my-postgres
```

Create a database:

```bash theme={null}
avn service database-create my-postgres mydb
```

Delete a database:

```bash theme={null}
avn service database-delete my-postgres mydb
```

### User management

List service users:

```bash theme={null}
avn service user-list my-postgres
```

Create a new user:

```bash theme={null}
avn service user-create my-postgres newuser
```

Reset user password:

```bash theme={null}
avn service user-password-reset my-postgres myuser
```

Delete a user:

```bash theme={null}
avn service user-delete my-postgres olduser
```

### Apache Kafka operations

#### Topic management

List topics:

```bash theme={null}
avn service topic-list my-kafka
```

Create a topic:

```bash theme={null}
avn service topic-create my-kafka \
  my-topic \
  --partitions 3 \
  --replication 2 \
  --retention 72h
```

Update topic configuration:

```bash theme={null}
avn service topic-update my-kafka my-topic \
  --retention 168h \
  --min-insync-replicas 2
```

Delete a topic:

```bash theme={null}
avn service topic-delete my-kafka my-topic
```

#### ACL management

List ACLs:

```bash theme={null}
avn service acl-list my-kafka
```

Add an ACL entry:

```bash theme={null}
avn service acl-add my-kafka \
  --permission read \
  --topic my-topic \
  --username myuser
```

Delete an ACL:

```bash theme={null}
avn service acl-delete my-kafka ACL_ID
```

### Connection information

Get connection details:

```bash theme={null}
avn service connection-info my-postgres
```

Get specific connection format:

```bash theme={null}
avn service connection-info my-kafka --format prometheus
```

### Service integrations

List available integration types:

```bash theme={null}
avn service integration-types-list
```

Create an integration:

```bash theme={null}
avn service integration-create \
  --integration-type datadog \
  --source-service my-postgres \
  --dest-endpoint my-datadog-endpoint
```

List integrations:

```bash theme={null}
avn service integration-list my-postgres
```

## Advanced features

### VPC management

List VPCs:

```bash theme={null}
avn vpc list
```

Create a VPC:

```bash theme={null}
avn vpc create \
  --cloud aws-us-east-1 \
  --network-cidr 10.0.0.0/24
```

Create a VPC peering connection:

```bash theme={null}
avn vpc peering-connection create \
  --project-vpc-id VPC_ID \
  --peer-cloud-account 123456789012 \
  --peer-vpc vpc-abcdef123456
```

### Service logs

View service logs:

```bash theme={null}
avn service logs my-postgres
```

Follow logs in real-time:

```bash theme={null}
avn service logs my-postgres --follow
```

### Metrics

Get service metrics:

```bash theme={null}
avn service metrics my-postgres --period day
```

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

### Query statistics

List slow queries (PostgreSQL/MySQL):

```bash theme={null}
avn service queries my-postgres
```

Reset query statistics:

```bash theme={null}
avn service queries-reset my-postgres
```

### Maintenance

Start maintenance immediately:

```bash theme={null}
avn service maintenance-start my-postgres
```

### Interactive shells

Open an interactive shell to a service:

<CodeGroup>
  ```bash PostgreSQL theme={null}
  avn service cli my-postgres
  ```

  ```bash Redis/Valkey theme={null}
  avn service cli my-redis
  ```
</CodeGroup>

## Configuration

### Output format

Get JSON output for any command:

```bash theme={null}
avn service list --json
```

Use custom formatting:

```bash theme={null}
avn service list --format '{service_name} {state} {plan}'
```

### Project switching

Switch between projects:

```bash theme={null}
avn project switch my-other-project
```

Run a single command against a different project:

```bash theme={null}
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:

```bash theme={null}
avn service types
```

View detailed service type information with all configuration options:

```bash theme={null}
avn service types -v
```

List available plans for a service type:

```bash theme={null}
avn service plans --service-type pg --cloud google-europe-north1
```

List available cloud regions:

```bash theme={null}
avn cloud list
```

## Scripting tips

### Error handling

```bash theme={null}
if avn service get my-service &> /dev/null; then
  echo "Service exists"
else
  echo "Service does not exist"
fi
```

### Parse JSON output

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="CI/CD integration">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Backup and disaster recovery">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Migration tasks">
    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Check CLI version

```bash theme={null}
avn --version
```

### Enable debug output

```bash theme={null}
avN_DEBUG=1 avn service list
```

### Re-authenticate

```bash theme={null}
avn user logout
avn user login your-email@example.com --token
```

## Related resources

* [Aiven CLI GitHub Repository](https://github.com/aiven/aiven-client)
* [Getting Started Tutorial (Video)](https://www.youtube.com/watch?v=nf3PPn5w6K8)
* [Aiven CLI Blog Post](https://aiven.io/blog/aiven-cmdline)
* [Aiven API Documentation](/tools/api)