Skip to main content

A command line interface to the Google Ads Query Language (GAQL). Run with `gaql` or `gaql-tools`

Project description


PyPI version PyPI downloads

A CLI for running GoogleAds queries.



  • pip install gaql
  • pipx install gaql (recommended)


The default mode. Runs either as a REPL, or as a one off command

- gaql [ACCOUNT_ID] - run in REPL mode
- gaql [ACCOUNT_ID] [WORDS*] - run a single query. Note depending on your shell you may need to quote some queries if you run like this.

--help show the help message; basically the below
-f|--format <csv|json|jsonl|proto> specify an output format
-o|--output <file> specify an output file. Based on the extension, format is inferred. Non REPL usage only

Examples, using 1-000-000-000 as our demo account id:

# opens a REPL with json lines as the output format
gaql -f jsonl 1-000-000-000

# runs the query against the given account, outputting to the terminal the results as json lines
gaql -f jsonl 1-000-000-000 'SELECT FROM campaign'

# runs the query against the given account, outputting to 'campaigns.jsonl' the result as json lines
gaql -o campaigns.jsonl 1-000-000-000 'SELECT FROM campaign'

tip: by default LIMIT 100 will be added to your queries. To override this behavior, simply define your own LIMIT X.

tip: the autocomplete will return only valid fields for the selected entity if you fill out the FROM <entity> part first.

Other tools

Used for useful common queries. Currently only supports getting all accounts under an MCC, to help when managing multiple accounts. The MCC is taken from the login_customer_id field.

  • gaql-tools queries clients


  • credentials come from the environment > the google .yaml file > a user provided credential file
  • credentials, settings, and history are stored in ./config/gaql/*. The credential file will only be present if you create it through a prompt (i.e you aren't using the ENV, or the YAML file Google specifies)

Ideas / TODO

  • tables as an output format
  • autocomplete for account ids (with caching)


We're using poetry for local development, package management, and publishing. pyenv is recommended for Python version management, and pipx for installation.

Build commands:

make develop - install a development version. run via `poetry run gaql <args>`
make publish - build and distribute to PyPi
make clean   - remove the existing build files
make format  - run black over the code
make lint    - lint and format the code


For sensitive security matters please contact


gaql-cli is licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gaql-1.10.0.tar.gz (87.5 kB view hashes)

Uploaded Source

Built Distribution

gaql-1.10.0-py3-none-any.whl (91.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page