# 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 <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:
```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 <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`
## 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 <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
```
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/getyourguide/gaql-cli",
"name": "gaql",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<3.12",
"maintainer_email": "",
"keywords": "gaql,google-ads,cli",
"author": "Ben Ryves",
"author_email": "bryves@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/74/ec/f7aa2daf6a33757101f7e31a3e5982951e1828adafeb1cec87d638247638/gaql-1.10.0.tar.gz",
"platform": null,
"description": "# GAQL CLI\n\n[](https://badge.fury.io/py/gaql)\n\n\nA CLI for running [GoogleAds queries](https://developers.google.com/google-ads/api/docs/query/overview).\n\n## Usage\n### Installing\n\n- `pip install gaql`\n- `pipx install gaql` (recommended)\n\n### Querying\nThe default mode. Runs either as a REPL, or as a one off command\n\n```bash\n- gaql [ACCOUNT_ID] - run in REPL mode\n- 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.\n\nflags:\n--help show the help message; basically the below\n-f|--format <csv|json|jsonl|proto> specify an output format\n-o|--output <file> specify an output file. Based on the extension, format is inferred. Non REPL usage only\n```\n\nExamples, using 1-000-000-000 as our demo account id:\n```bash\n# opens a REPL with json lines as the output format\ngaql -f jsonl 1-000-000-000\n\n# runs the query against the given account, outputting to the terminal the results as json lines\ngaql -f jsonl 1-000-000-000 'SELECT campaign.id FROM campaign'\n\n# runs the query against the given account, outputting to 'campaigns.jsonl' the result as json lines\ngaql -o campaigns.jsonl 1-000-000-000 'SELECT campaign.id FROM campaign'\n```\n\n**tip**: by default `LIMIT 100` will be added to your queries. To override this behavior, simply define your own `LIMIT X`.\n\n**tip**: the autocomplete will return only valid fields for the selected entity if you fill out the `FROM <entity>` part\nfirst.\n\n### Other tools\nUsed 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.\n- `gaql-tools queries clients`\n\n## Notes\n- credentials come from the environment > the google .yaml file > a user provided credential file\n- 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)\n\n## Ideas / TODO\n- tables as an output format\n- autocomplete for account ids (with caching)\n\n## Development\nWe're using [poetry](https://github.com/python-poetry/poetry) for local development, package management, and publishing. `pyenv` is\nrecommended for Python version management, and `pipx` for installation.\n\nBuild commands:\n\n```\nmake develop - install a development version. run via `poetry run gaql <args>`\nmake publish - build and distribute to PyPi\nmake clean - remove the existing build files\nmake format - run black over the code\nmake lint - lint and format the code\n```\n\n## Security\nFor sensitive security matters please contact security@getyourguide.com.\n\n## Legal\ngaql-cli is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full text.\n",
"bugtrack_url": null,
"license": "",
"summary": "A command line interface to the Google Ads Query Language (GAQL). Run with `gaql` or `gaql-tools`",
"version": "1.10.0",
"project_urls": {
"Homepage": "https://github.com/getyourguide/gaql-cli",
"Repository": "https://github.com/getyourguide/gaql-cli"
},
"split_keywords": [
"gaql",
"google-ads",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6e3df7cf2b6a62f5ba431913d3981dc4d1e2838da8a07178316c3262050ae59e",
"md5": "89618a0c40cc3f07a27cd0f10a560bb8",
"sha256": "a27f0d555ecaf7aa291f949e4359be59d9fdc5305bd9c195510dc2cf735eee92"
},
"downloads": -1,
"filename": "gaql-1.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "89618a0c40cc3f07a27cd0f10a560bb8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<3.12",
"size": 91291,
"upload_time": "2023-11-01T16:33:25",
"upload_time_iso_8601": "2023-11-01T16:33:25.887350Z",
"url": "https://files.pythonhosted.org/packages/6e/3d/f7cf2b6a62f5ba431913d3981dc4d1e2838da8a07178316c3262050ae59e/gaql-1.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "74ecf7aa2daf6a33757101f7e31a3e5982951e1828adafeb1cec87d638247638",
"md5": "0c180d99a0cf62c68e204b85e075a72b",
"sha256": "c084d0c055876e25836f98f8d827c7940517675fafc741ad66b7f900a836328e"
},
"downloads": -1,
"filename": "gaql-1.10.0.tar.gz",
"has_sig": false,
"md5_digest": "0c180d99a0cf62c68e204b85e075a72b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<3.12",
"size": 87534,
"upload_time": "2023-11-01T16:33:27",
"upload_time_iso_8601": "2023-11-01T16:33:27.858485Z",
"url": "https://files.pythonhosted.org/packages/74/ec/f7aa2daf6a33757101f7e31a3e5982951e1828adafeb1cec87d638247638/gaql-1.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-01 16:33:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "getyourguide",
"github_project": "gaql-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gaql"
}
JSON
