{"id":24344330,"url":"https://github.com/aiven/aiven-client","last_synced_at":"2025-05-15T17:07:41.887Z","repository":{"id":3193084,"uuid":"48698708","full_name":"aiven/aiven-client","owner":"aiven","description":"aiven-client (avn) is the official command-line client for Aiven","archived":false,"fork":false,"pushed_at":"2025-05-08T06:57:31.000Z","size":1226,"stargazers_count":86,"open_issues_count":16,"forks_count":33,"subscribers_count":73,"default_branch":"main","last_synced_at":"2025-05-08T07:32:50.078Z","etag":null,"topics":["aiven","cli","client"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aiven.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-12-28T15:26:21.000Z","updated_at":"2025-05-08T06:57:23.000Z","dependencies_parsed_at":"2024-01-16T19:20:58.808Z","dependency_job_id":"d8912711-4b48-4982-a370-60bcf6f6623a","html_url":"https://github.com/aiven/aiven-client","commit_stats":null,"previous_names":[],"tags_count":90,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiven%2Faiven-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiven%2Faiven-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiven%2Faiven-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiven%2Faiven-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aiven","download_url":"https://codeload.github.com/aiven/aiven-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiven","cli","client"],"created_at":"2025-01-18T09:33:48.814Z","updated_at":"2025-05-15T17:07:36.879Z","avatar_url":"https://github.com/aiven.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"Aiven Client |BuildStatus|_\n###########################\n\n.. |BuildStatus| image:: https://github.com/aiven/aiven-client/workflows/Build%20Aiven%20Client/badge.svg?branch=main\n.. _BuildStatus: https://github.com/aiven/aiven-client/actions\n\nAiven is a next-generation managed cloud services platform.  Its focus is in\nease of adoption, high fault resilience, customer's peace of mind and\nadvanced features at competitive price points.  See https://aiven.io/ for\nmore information about the backend service.\n\naiven-client (``avn``) is the official command-line client for Aiven.\n\n.. contents::\n\n\n.. _platform-requirements:\n\nGetting Started\n===============\n\nRequirements:\n\n*  Python 3.8 or later\n\n*  Requests_\n\n*  For Windows and OSX, certifi_ is also needed\n\n.. _`Requests`: http://www.python-requests.org/\n.. _`certifi`: https://github.com/certifi/python-certifi\n\n.. _installation:\n\nInstall from PyPi\n-----------------\n\nPypi installation is the recommended route for most users::\n\n  $ python3 -m pip install aiven-client\n\n\nBuild an RPM Package\n--------------------\n\nIt is also possible to build an RPM::\n\n  $ make rpm\n\nCheck Installation\n------------------\n\nTo check that the tool is installed and working, run it without arguments::\n\n  $ avn\n\nIf you see usage output, you're all set.\n\n  **Note:** On Windows you may need to use ``python3 -m aiven.client`` instead of ``avn``.\n\nLog In\n------\n\nThe simplest way to use Aiven CLI is to authenticate with the username and\npassword you use on Aiven::\n\n  $ avn user login \u003cyou@example.com\u003e\n\nThe command will prompt you for your password.\n\nYou can also use an access token generated in the Aiven Console::\n\n  $ avn user login \u003cyou@example.com\u003e --token\n\nYou will be prompted for your access token as above.\n\nIf you are registered on Aiven through the AWS or GCP marketplace, then you need to specify an additional argument ``--tenant``. Currently the supported value are ``aws`` and ``gcp``, for example::\n\n  $ avn user login \u003cyou@example.com\u003e --tenant aws\n\n.. _help-command:\n.. _basic-usage:\n\nUsage\n=====\n\nSome handy hints that work with all commands:\n\n*  The ``avn help`` command shows all commands and can *search* for a command,\n   so for example ``avn help kafka topic`` shows commands with kafka *and*\n   topic in their description.\n\n*  Passing ``-h`` or ``--help`` gives help output for any command. Examples:\n   ``avn --help`` or ``avn service --help``.\n\n*  All commands will output the raw REST API JSON response with ``--json``,\n   we use this extensively ourselves in conjunction with\n   `jq \u003chttps://stedolan.github.io/jq/\u003e`__.\n\n\n.. _login-and-users:\n\nAuthenticate: Logins and Tokens\n-------------------------------\n\nLogin::\n\n  $ avn user login \u003cyou@example.com\u003e\n\nLogout (revokes current access token, other sessions remain valid)::\n\n  $ avn user logout\n\nExpire all authentication tokens for your user, logs out all web console sessions, etc.\nYou will need to login again after this::\n\n $ avn user tokens-expire\n\nManage individual access tokens::\n\n $ avn user access-token list\n $ avn user access-token create --description \u003cusage_description\u003e [--max-age-seconds \u003csecs\u003e] [--extend-when-used]\n $ avn user access-token update \u003ctoken|token_prefix\u003e --description \u003cnew_description\u003e\n $ avn user access-token revoke \u003ctoken|token_prefix\u003e\n\nNote that the system has hard limits for the number of tokens you can create. If you're\npermanently done using a token you should always use ``user access-token revoke`` operation\nto revoke the token so that it does not count towards the quota.\n\nAlternatively, you can add 2 JSON files, first create a default config in ``~/.config/aiven/aiven-credentials.json`` containing the JSON with an ``auth_token``::\n\n  {\n      \"auth_token\": \"ABC1+123...TOKEN==\",\n      \"user_email\": \"you@example.com\"\n  }\n\nSecond create a default config in ``~/.config/aiven/aiven-client.json`` containing the json with the ``default_project``::\n\n  {\"default_project\": \"yourproject-abcd\"}\n\n.. _clouds:\n\nChoose your Cloud\n-----------------\n\nList available cloud regions::\n\n  $ avn cloud list\n\n.. _projects:\n\nWorking with Projects\n---------------------\n\nList projects you are a member of::\n\n  $ avn project list\n\nProject commands operate on the currently active project or the project\nspecified with the ``--project NAME`` switch. The active project cab be changed\nwith the ``project switch`` command::\n\n  $ avn project switch \u003cprojectname\u003e\n\nShow active project's details::\n\n  $ avn project details\n\nCreate a project and set the default cloud region for it::\n\n  $ avn project create myproject --cloud aws-us-east-1\n\nDelete an empty project::\n\n  $ avn project delete myproject\n\nList authorized users in a project::\n\n  $ avn project user-list\n\nInvite an existing Aiven user to a project::\n\n  $ avn project user-invite somebody@example.com\n\nRemove a user from the project::\n\n  $ avn project user-remove somebody@example.com\n\nView project management event log::\n\n  $ avn events\n\n.. _services:\n\nExplore Existing Services\n-------------------------\n\nList services (of the active project)::\n\n  $ avn service list\n\nList services in a specific project::\n\n  $ avn service list --project proj2\n\nList only a specific service::\n\n  $ avn service list db1\n\nVerbose list (includes connection information, etc.)::\n\n  $ avn service list db1 -v\n\nFull service information in JSON, as it is returned by the Aiven REST API::\n\n  $ avn service list db1 --json\n\nOnly a specific field in the output, custom formatting::\n\n  $ avn service list db1 --format \"The service is at {service_uri}\"\n\nView service log entries (most recent entries and keep on following logs, other options can be used to get history)::\n\n  $ avn service logs db1 -f\n\n.. _launching-services:\n\nLaunch Services\n---------------\n\nView available service plans::\n\n  $ avn service plans\n\nLaunch a PostgreSQL service::\n\n  $ avn service create mydb -t pg --plan hobbyist\n\nView service type specific options, including examples on how to set them::\n\n  $ avn service types -v\n\nLaunch a PostgreSQL service of a specific version (see above command)::\n\n  $ avn service create mydb96 -t pg --plan hobbyist -c pg_version=9.6\n\nUpdate a service's list of allowed client IP addresses. Note that a list of multiple\nvalues is provided as a comma separated list::\n\n  $ avn service update mydb96 -c ip_filter=10.0.1.0/24,10.0.2.0/24,1.2.3.4/32\n\nOpen psql client and connect to the PostgreSQL service (also available for InfluxDB)::\n\n  $ avn service cli mydb96\n\nUpdate a service to a different plan AND move it to another cloud region::\n\n  $ avn service update mydb --plan startup-4 --cloud aws-us-east-1\n\nPower off a service::\n\n  $ avn service update mydb --power-off\n\nPower on a service::\n\n  $ avn service update mydb --power-on\n\nTerminate a service (all data will be gone!)::\n\n  $ avn service terminate mydb\n\nManaging service users\n----------------------\n\nSome service types support multiple users (e.g. PostgreSQL database users).\n\nList, add and delete service users::\n\n  $ avn service user-list\n  $ avn service user-create\n  $ avn service user-delete\n\nFor Valkey services it's possible to create users with ACLs_::\n\n  $ avn service user-create --username new_user --valkey-acl-keys=\"prefix* another_key\" --valkey-acl-commands=\"+set\" --valkey-acl-categories=\"-@all +@admin\" --valkey-acl-channels=\"prefix* some_chan\" my-valkey-service\n\n.. _`ACLs`: https://valkey.io/docs/topics/acl\n\nService users are created with strong random passwords.\n\nService Integrations\n--------------------\n`Service integrations \u003chttps://aiven.io/service-integrations\u003e`_ allow to link Aiven services to other Aiven services or to services\noffered by other companies for example for logging. Some examples for various diffenent integrations:\n`Google cloud logging`_, `AWS Cloudwatch logging`_, `Remote syslog integration`_ and `Getting started with Datadog`_.\n\n.. _`Google cloud logging`: https://help.aiven.io/en/articles/4209837-sending-service-logs-to-google-cloud-logging\n.. _`AWS Cloudwatch logging`: https://help.aiven.io/en/articles/4134821-sending-service-logs-to-aws-cloudwatch\n.. _`Remote syslog integration`: https://help.aiven.io/en/articles/2933115-remote-syslog-integration\n.. _`Getting started with Datadog`: https://help.aiven.io/en/articles/1759208-getting-started-with-datadog\n\nList service integration endpoints::\n\n    $ avn service integration-endpoint-list\n\nList all available integration endpoint types for given project::\n\n    $ avn service integration-endpoint-types-list --project \u003cproject\u003e\n\nCreate a service integration endpoint::\n\n    $ avn service integration-endpoint-create --project \u003cproject\u003e --endpoint-type \u003cendpoint type\u003e --endpoint-name \u003cendpoint name\u003e --user-config-json \u003cuser configuration as json\u003e\n    $ avn service integration-endpoint-create --project \u003cproject\u003e --endpoint-type \u003cendpoint type\u003e --endpoint-name \u003cendpoint name\u003e -c \u003cKEY=VALUE type user configuration\u003e\n\nUpdate a service integration endpoint::\n\n    $ avn service integration-endpoint-update --project \u003cproject\u003e --user-config-json \u003cuser configuration as json\u003e \u003cendpoint id\u003e\n    $ avn service integration-endpoint-update --project \u003cproject\u003e -c \u003cKEY=VALUE type user configuration\u003e \u003cendpoint id\u003e\n\nDelete a service integration endpoint::\n\n    $ avn service integration-endpoint-delete --project \u003cproject\u003e  \u003cendpoint_id\u003e\n\nList service integrations::\n\n    $ avn service integration-list \u003cservice name\u003e\n\nList all available integration types for given project::\n\n    $ avn service integration-types-list --project \u003cproject\u003e\n\nCreate a service integration::\n\n    $ avn service integration-create --project \u003cproject\u003e -t \u003cintegration type\u003e -s \u003csource service\u003e -d \u003cdest service\u003e -S \u003csource endpoint id\u003e -D \u003cdestination endpoint id\u003e --user-config-json \u003cuser configuration as json\u003e\n    $ avn service integration-create --project \u003cproject\u003e -t \u003cintegration type\u003e -s \u003csource service\u003e -d \u003cdest service\u003e -S \u003csource endpoint id\u003e -D \u003cdestination endpoint id\u003e -c \u003cKEY=VALUE type user configuration\u003e\n\nUpdate a service integration::\n\n    $ avn service integration-update --project \u003cproject\u003e --user-config-json \u003cuser configuration as json\u003e \u003cintegration_id\u003e\n    $ avn service integration-update --project \u003cproject\u003e -c \u003cKEY=VALUE type user configuration\u003e \u003cintegration_id\u003e\n\nDelete a service integration::\n\n    $ avn service integration-delete --project \u003cproject\u003e \u003cintegration_id\u003e\n\nCustom Files\n------------\n\nListing files::\n\n    $ avn service custom-file list --project \u003cproject\u003e \u003cservice_name\u003e\n\nReading file::\n\n    $ avn service custom-file get --project \u003cproject\u003e --file_id \u003cfile_id\u003e [--target_filepath \u003cfile_path\u003e] [--stdout_write] \u003cservice_name\u003e\n\n\nUploading new files::\n\n    $ avn service custom-file upload --project \u003cproject\u003e --file_type \u003cfile_type\u003e --file_path \u003cfile_path\u003e --file_name \u003cfile_name\u003e \u003cservice_name\u003e\n\nUpdating existing files::\n\n    $ avn service custom-file update --project \u003cproject\u003e --file_path \u003cfile_path\u003e --file_id \u003cfile_id\u003e \u003cservice_name\u003e\n\n.. _teams:\n\nWorking with Teams\n------------------\n\nList account teams::\n\n  $ avn account team list \u003caccount_id\u003e\n\nCreate a team::\n\n  $ avn account team create --team-name \u003cteam_name\u003e \u003caccount_id\u003e\n\nDelete a team::\n\n  $ avn account team delete --team-id \u003cteam_id\u003e \u003caccount_id\u003e\n\nAttach team to a project::\n\n  $ avn account team project-attach --team-id \u003cteam_id\u003e --project \u003cproject_name\u003e \u003caccount_id\u003e --team-type \u003cadmin|developer|operator|read_only\u003e\n\n\nDetach team from project::\n\n  $ avn account team project-detach --team-id \u003cteam_id\u003e --project \u003cproject_name\u003e \u003caccount_id\u003e\n\nList projects associated to the team::\n\n  $ avn account team project-list --team-id \u003cteam_id\u003e \u003caccount_id\u003e\n\nList members of the team::\n\n  $ avn account team user-list --team-id \u003cteam_id\u003e \u003caccount_id\u003e\n\nInvite a new member to the team::\n\n  $ avn account team user-invite --team-id \u003cteam_id\u003e \u003caccount_id\u003e \u003csomebody@example.com\u003e\n\nSee the list of pending invitations::\n\n  $ avn account team user-list-pending --team-id \u003cteam_id\u003e \u003caccount_id\u003e\n\nRemove user from the team::\n\n  $ avn account team user-delete --team-id \u003cteam_id\u003e --user-id \u003cuser_id\u003e \u003caccount_id\u003e\n\n\n.. _oauth2-clients:\n\nConfiguring OAuth2 Clients\n--------------------------\n\nList configured OAuth2 clients::\n\n  $ avn account oauth2-client list \u003caccount_id\u003e\n\nGet a configured OAuth2 client's configuration::\n\n  $ avn account oauth2-client list \u003caccount_id\u003e --oauth2-client-id \u003cclient_id\u003e\n\nCreate a new OAuth2 client information::\n\n  $ avn account oauth2-client create \u003caccount_id\u003e --name \u003capp_name\u003e -d \u003capp_description\u003e --redirect-uri \u003credirect_uri\u003e\n\nDelete an OAuth2 client::\n\n  $ avn account oauth2-client delete \u003caccount_id\u003e --oauth2-client-id \u003cclient_id\u003e\n\nList an OAuth2 client's redirect URIs::\n\n  $ avn account oauth2-client redirect-list \u003caccount_id\u003e --oauth2-client-id \u003cclient_id\u003e\n\nCreate a new OAuth2 client redirect URI::\n\n  $ avn account oauth2-client redirect-create \u003caccount_id\u003e --oauth2-client-id \u003cclient_id\u003e --redirect-uri \u003credirect_uri\u003e\n\nDelete an OAuth2 client redirect URI::\n\n  $ avn account oauth2-client redirect-delete \u003caccount_id\u003e --oauth2-client-id \u003cclient_id\u003e --redirect-uri-id \u003credirect_uri_id\u003e\n\nList an OAuth2 client's secrets::\n\n  $ avn account oauth2-client secret-list \u003caccount_id\u003e --oauth2-client-id \u003cclient_id\u003e\n\nCreate a new OAUth2 client secret::\n\n  $ avn account oauth2-client secret-create \u003caccount_id\u003e --oauth2-client-id \u003cclient_id\u003e\n\nDelete an OAuth2 client's secret::\n\n  $ avn account oauth2-client secret-delete \u003caccount_id\u003e --oauth2-client-id \u003cclient_id\u003e --secret-id \u003csecret_id\u003e\n\n\nExtra Features\n==============\n\n.. _shell-completions:\n\nAutocomplete\n------------\n\navn supports shell completions. It requires an optional dependency: argcomplete. Install it::\n\n  $ python3 -m pip install argcomplete\n\nTo use completions in bash, add following line to ``~/.bashrc``::\n\n  eval \"$(register-python-argcomplete avn)\"\n\nFor more information (including completions usage in other shells) see https://kislyuk.github.io/argcomplete/.\n\nAuth Helpers\n------------\n\nWhen you spin up a new service, you'll want to connect to it. The ``--json`` option combined with the `jq \u003chttps://stedolan.github.io/jq/\u003e`_ utility is a good way to grab the fields you need for your specific service. Try this to get the connection string::\n\n  $ avn service get --json \u003cservice\u003e | jq \".service_uri\"\n\nEach project has its own CA cert, and other services (notably Kafka) use mutualTLS so you will also need the ``service.key`` and ``service.cert`` files too for those. Download all three files to the local directory::\n\n  $ avn service user-creds-download --username avnadmin \u003cservice\u003e\n\nFor working with `kcat \u003chttps://github.com/edenhill/kcat\u003e`_ (see also our `help article \u003chttps://developer.aiven.io/docs/products/kafka/howto/kcat.html\u003e`_ ) or the command-line tools that ship with Kafka itself, a keystore and trustore are needed. By specifying which user's creds to use, and a secret, you can generate these via ``avn`` too::\n\n  $ avn service user-kafka-java-creds --username avnadmin -p t0pS3cr3t \u003cservice\u003e\n\nContributing\n============\n\nCheck the `CONTRIBUTING \u003chttps://github.com/aiven/aiven-client/blob/main/.github/CONTRIBUTING.md\u003e`_ guide for details on how to contribute to this repository.\n\nKeep Reading\n============\n\nWe maintain some other resources that you may also find useful:\n\n* `Command Line Magic with avn \u003chttps://aiven.io/blog/command-line-magic-with-the-aiven-cli\u003e`__\n* `Managing Billing Groups via CLI \u003chttps://help.aiven.io/en/articles/4720981-using-billing-groups-via-cli\u003e`__\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiven%2Faiven-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faiven%2Faiven-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiven%2Faiven-client/lists"}