Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

Build Status PyPI Downloads image image Join the chat at


AthenaCLI is a command line interface (CLI) for the Athena service that can do auto-completion and syntax highlighting, and is a proud member of the dbcli community.

Quick Start


Install via pip

If you already know how to install python packages, then you can simply do:

$ pip install athenacli

Install via brew

Homebrew users can install by:

$ brew install athenacli

If you don't know how to install python packages, please check the Install page for more options (e.g docker)


A config file is automatically created at ~/.athenacli/athenaclirc at first launch (run athenacli). See the file itself for a description of all available options.

Below 4 variables are required. If you are a user of aws cli, you can refer to awsconfig file to see how to reuse credentials configuration of aws cli.

# AWS credentials
aws_access_key_id = ''
aws_secret_access_key = ''
region = '' # e.g us-west-2, us-east-1

# Amazon S3 staging directory where query results are stored.
# NOTE: S3 should in the same region as specified above.
# The format is 's3://<your s3 directory path>'
s3_staging_dir = ''

# Name of athena workgroup that you want to use
work_group = '' # e.g. primary

or you can also use environment variables:

$ export AWS_DEFAULT_REGION=us-west-2
$ export AWS_ATHENA_S3_STAGING_DIR=s3://YOUR_S3_BUCKET/path/to/

Create a table

$ athenacli -e examples/create_table.sql

You can find examples/create_table.sql here.

Run a query

$ athenacli -e 'select elb_name, request_ip from elb_logs LIMIT 10'


$ athenacli [<database_name>]


  • Auto-completes as you type for SQL keywords as well as tables and columns in the database.
  • Syntax highlighting.
  • Smart-completion will suggest context-sensitive completion.
    • SELECT * FROM <tab> will only show table names.
    • SELECT * FROM users WHERE <tab> will only show column names.
  • Pretty prints tabular data and various table formats.
  • Some special commands. e.g. Favorite queries.
  • Alias support. Column completions will work even when table names are aliased.

Please refer to the Features page for the screenshots of above features.


$ athenacli --help

A Athena terminal client with auto-completion and syntax highlighting.

    - athenacli
    - athenacli my_database

-e, --execute TEXT            Execute a command (or a file) and quit.
-r, --region TEXT             AWS region.
--aws-access-key-id TEXT      AWS access key id.
--aws-secret-access-key TEXT  AWS secretaccess key.
--s3-staging-dir TEXT         Amazon S3 staging directory where query
                                results are stored.
--work-group TEXT             Amazon Athena workgroup in which query is run, default is primary
--athenaclirc PATH            Location of athenaclirc file.
--help                        Show this message and exit.

Please go to the Usages for detailed information on how to use AthenaCLI.


If you're interested in contributing to this project, first of all I would like to extend my heartfelt gratitude. I've written a small doc to describe how to get this running in a development setup.

Please feel free to reach out to me if you need help. My email: zhuzhaolong0 AT gmail com


Please refer to the FAQs for other information, e.g. "How can I get support for athenacli?".


A special thanks to Amjith Ramanujam for creating pgcli and mycli, which inspired me to create this AthenaCLI, and AthenaCLI is created based on a clone of mycli.

Thanks to Jonathan Slenders for creating the Python Prompt Toolkit, which leads me to pgcli and mycli. It's a lot of fun playing with this library.

Thanks to PyAthena for a pure python adapter to Athena database.

Last but not least, thanks my team and manager encourage me to work on this hobby project.

Similar projects