Skip to main content

Google Ads Control CLI and Prompt

Project description

Google Ads API CLI and Prompt

Google Ads Interface for humans.

This is a work in progress, please open an issue if you find any bugs or have any suggestions.


  • A command line tool for executing GAQL queries against the Google Ads API. Like psql for the Google Ads API.
  • A command line tool for managing Google Ads resources. Like kubectl for the Google Ads API.
  • Centralized configuration with multiple account management
  • Automatically update refresh token
  • Python API with Pandas integration


pip install adsctl

Getting started


  • All the requirements to use the Google Ads API including a Developer Token and OAuth2 credentials
  • See Google Ads API Quickstart for more details.


This project manages it's own configuration files. To create the configuration file run:

adsctl config

# Open the location of the config files
adsctl config explore

Open the new default config file and fill it with your credentials: Dev Token, Client ID, Client Secret and Customer ID.

To login and get a refresh token:

adsctl auth <path-to-secret.json>

The token is saved automatically in the config file. You can see it by running:

# View config
adsctl config view

Multiple Accounts

You can manage multiple accounts in the config file by adding TOML sections.

current_account = "default"

[... default account ...]

developer_token = ""
customer_id = ""
login_customer_id = ""

client_id = ""
client_secret = ""

Set the current account:

$ adsctl config set-account another
$ adsctl config get-account

GAQL Prompt

An interactive shell for executing GAQL queries against the Google Ads API.

$ gaql

>>> SELECT, FROM campaign ORDER BY
|    | resourceName                | name    |          id |
|  0 | customers/XXX/campaigns/YYY | name1   | 10000000000 |
|  1 | customers/XXX/campaigns/YYY | name2   | 10000000000 |
|  2 | customers/XXX/campaigns/YYY | name3   | 10000000000 |

By default it uses the it in table format but you can control the output format with the -o option:

# Print the plain protobuf response
$ gaql -o plain

# Print the contents of a CSV file
$ gaql -o csv

You can also run a single inline command and redirect the output to a file:

gaql -c 'SELECT, FROM campaign ORDER BY' -o csv > my-query.csv

This assumes only table is returned but in more complex queries that include other resources or when using metrics or segments multiple tables are created. On those cases use the -o csv-files flag to save each table to a different file based on the table name.

$ gaql -c 'SELECT, FROM campaign ORDER BY' -o csv-files

$ ls

Query variables

You can specify one or more variables using the jinja syntax, those variables will be replaced with the values specified in the -v options.

gaql -c 'SELECT, FROM campaign WHERE = {{ id }} ORDER BY' -v id=123456789

You can also pass -v without a command and use this the variables in the prompt queries:

$ gaql -v id=123456789 -v field=name

>>> SELECT, campaign.{{ field }} FROM campaign WHERE = {{ id }} ORDER BY

Other options

You can overwrite the account and customer ID using the -a and -i options. See gaql --help for more details.


Campaign Management

Status management

adsctl campaign -i <campaign-id> status enabled
adsctl campaign -i <campaign-id> status paused

Update budget

adsctl campaign -i <campaign-id> budget <amount>

Python API

You can also use the Python API to easily execute GAQL queries and get the results as a Python dict or pandas DataFrame.

import adsctl as ads

# Read config file and creates the Google Ads client
google_ads = ads.GoogleAds()

# Execute GAQL query
get_campaigns_query = """
FROM campaign
  AND campaign.status != '{{ status }}'

tables = adsctl.query(get_campaigns_query, params={"status": "REMOVED"}})

# Print Pandas DataFrames
for table_name, table in tables.items():
    print(table, "\n")
                                 resourceName   status  ...                      name optimizationScore
0  customers/XXXXXXXXXX/campaigns/YYYYYYYYYYY  ENABLED  ...               my-campaign          0.839904
[1 rows x 6 columns]

  clicks costMicros       ctr    averageCpc impressions
0    210    6730050  0.011457  32047.857143       18330

                                       resourceName amountMicros
0  customers/XXXXXXXXXX/campaignBudgets/ZZZZZZZZZZZ      1000000

Or directly get a client to use search_stream directly:

gads_client = google_ads.create_client()
stream = self.search_stream(query, client=myclient)

for batch in stream:
    for row in batch.results:


This is not an official Google product.

This repository is maintained by a Googler but is not a supported Google product. Code and issues here are answered by maintainers and other community members on GitHub on a best-effort basis.

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

adsctl-0.3.0.tar.gz (23.7 kB view hashes)

Uploaded Source

Built Distribution

adsctl-0.3.0-py3-none-any.whl (26.2 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