https://github.com/getyourguide/gaql-cli
A command line interface to the Google Ads Query Language (GAQL)
https://github.com/getyourguide/gaql-cli
cli gaql google google-ads repl
Last synced: 3 months ago
JSON representation
A command line interface to the Google Ads Query Language (GAQL)
- Host: GitHub
- URL: https://github.com/getyourguide/gaql-cli
- Owner: getyourguide
- License: apache-2.0
- Created: 2020-04-28T10:16:29.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-07-01T15:01:28.000Z (3 months ago)
- Last Synced: 2025-07-01T15:16:50.937Z (3 months ago)
- Topics: cli, gaql, google, google-ads, repl
- Language: Python
- Size: 1010 KB
- Stars: 25
- Watchers: 56
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# GAQL CLI
[](https://badge.fury.io/py/gaql)
A CLI for running [GoogleAds queries](https://developers.google.com/google-ads/api/docs/query/overview).
## Usage
### Installing
- `pip install gaql`
- `pipx install gaql` (recommended)
### Querying
The default mode. Runs either as a REPL, or as a one off command
```bash
- 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.
flags:
--help show the help message; basically the below
-f|--format specify an output format
-o|--output 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:
```bash
# 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 campaign.id 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 campaign.id 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 ` 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`
## Notes
- 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)
## Development
We're using [poetry](https://github.com/python-poetry/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 `
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
```
## Security
For sensitive security matters please contact security@getyourguide.com.
## Legal
gaql-cli is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full text.