The aanalytics2 package ships with an interactive command-line interface (CLI).
It gives you a terminal REPL to explore and manage your Adobe Analytics account without writing Python code.
The CLI wraps the Analytics class and the RequestCreator class. Every method that exists on those classes has a corresponding command.
The CLI is included in the package and becomes available after installation:
pip install aanalytics2You can also invoke it directly as a Python module without a registered entry point:
python -m aanalytics2.cliThe CLI reads credentials from the same JSON config file used by the Python library.
Two optional CLI-specific fields can be added: companyId and rsid.
{
"org_id": "<your IMS org ID>",
"client_id": "<your client ID>",
"secret": "<your secret>",
"scopes": "<your OAuth scopes>",
"companyId": "<your globalCompanyId>",
"rsid": "<your default report suite ID>"
}The companyId field skips the interactive company-selection prompt at startup.
The rsid field pre-sets the default report suite for the session.
You can generate a blank credentials file with:
import aanalytics2
aanalytics2.createConfigFile()Then add companyId and rsid manually before launching the CLI.
If no config file is found (e.g. the default config_analytics.json does not exist), the CLI falls back to individual credential parameters, sourced from either the config command's flags or from environment variables — useful on servers where dropping a JSON file on disk isn't practical.
Environment variables:
AANALYTICS2_ORG_IDAANALYTICS2_CLIENT_IDAANALYTICS2_SECRETAANALYTICS2_SCOPESAANALYTICS2_TECH_ID(optional)AANALYTICS2_COMPANY_ID(optional — same role ascompanyIdin the config file)AANALYTICS2_RSID(optional — same role asrsidin the config file)
export AANALYTICS2_ORG_ID="<your IMS org ID>"
export AANALYTICS2_CLIENT_ID="<your client ID>"
export AANALYTICS2_SECRET="<your secret>"
export AANALYTICS2_SCOPES="<your OAuth scopes>"
aanalytics2A config file, when present, still takes priority over environment variables — this is purely a fallback for when one isn't found. See config for using individual parameters directly instead of environment variables.
aanalytics2 [-cf config.json] [-cid companyId] [-rsid rsid] [-v] [-cmd "command"]Arguments:
-cf/--config_file: OPTIONAL : Path to the JSON config file. Default isconfig_analytics.jsonin the current directory.-cid/--company_id: OPTIONAL : Override theglobalCompanyId. Takes precedence over the value in the config file.-rsid/--report_suite_id: OPTIONAL : Override the default RSID for the session.-v/--verbose: OPTIONAL : Enable verbose HTTP output.-cmd/--command: OPTIONAL : Run a single command non-interactively and exit immediately.
When the CLI starts, it loads the config file, acquires an OAuth token, resolves the company ID, and connects to the Analytics API.
If no companyId is found in the flags or the config file, it calls getCompanyId() and displays a list of accessible companies for you to pick from.
# Use the default config file in the current directory
aanalytics2
# Specify a config file and a default RSID
aanalytics2 -cf ~/credentials/prod.json -rsid myprodrsidThe prompt tells you which company and report suite are active at all times.
# Company connected, no RSID set yet
mycompanyid>
# Company connected, RSID set
mycompanyid:myprodrsid>
# Inside the RequestCreator sub-shell
[request:myprodrsid]>
Use set_rsid at any point to change the active report suite for the session, and set_company_id to switch companies (this also reconnects Analytics for the new company).
help # grouped list of all available commands
help <command> # usage and argument details for a specific command
Pass -cmd to run a single command and exit. This is useful for scripting and cron jobs.
# Export all segments to CSV
aanalytics2 -cf config.json -cmd "get_segments -fn segments.csv"
# Filter dimensions for a given RSID
aanalytics2 -cf config.json -rsid myprodrsid -cmd "get_dimensions -f prop"Most commands share the following optional arguments:
-rsid: OPTIONAL : Report suite ID for this command. When a session RSID is set withset_rsid, this argument is optional — the session value is used as the default. When no session RSID is set,-rsidis required.-f/--filter: OPTIONAL : Case-insensitive substring filter, matched against every column of each result row. Applied locally, after the data has already been retrieved from the API — it does not change what is requested from Adobe Analytics, it only narrows what is displayed/saved.-sv/--save: OPTIONAL : Save the command output to a CSV file at the given path (e.g.-sv output.csv). If omitted, the result is only printed to the terminal and nothing is written to disk.-fn/--filename: OPTIONAL : Used onget_dimensions,get_metrics,get_calculated_metrics, andget_segments— these commands always save their result to CSV, so there is no on/off switch for saving.-fnonly overrides the default filename (e.g.dimensions_<rsid>.csv); omitting it just keeps the default name.-d/--definition: OPTIONAL or REQUIRED : Path to a JSON file used as the object definition or request body for create/update commands.-n: OPTIONAL : Limit the number of results returned. Onget_reportandrequest_creator run,inf(the default) retrieves all rows.
All delete commands print a confirmation prompt before executing:
Delete segment 's123456789'? [y/N]
Type y or yes to confirm. Anything else cancels the operation.
These commands manage the CLI session itself.
Reload the configuration and reconnect.
Useful when you want to switch credentials without restarting the shell.
config [-cf path/to/config.json] [-org_id ID] [-client_id ID] [-secret SECRET] [-scopes SCOPES] [-tech_id ID]
By default this loads -cf (or the current config file). If -org_id, -client_id, -secret, or -scopes are passed, they take priority over the config file and are used to build the credentials directly — any of them left unset falls back to the matching AANALYTICS2_* environment variable (see Configuring without a file).
Example — switching to a different set of credentials without a file, e.g. sourced from a secrets manager into environment variables at deploy time:
mycompanyid> config -org_id 1234@AdobeOrg -client_id abcd1234 -secret ****** -scopes ent_analytics_bulk_ingest_sdk
Connected to company: othercompanyid
List all Adobe Analytics companies accessible with the current credentials.
get_company_id [-sv file.csv]
Set or change the company ID for the session, and reconnect Analytics against it.
Useful after get_company_id reveals a company you want to switch to without restarting the shell.
set_company_id <company_id>
Example:
mycompanyid> set_company_id otherclientid
Company ID set to otherclientid
otherclientid>
Set or change the default RSID for the session.
Once set, all commands that require a report suite ID will use it automatically.
set_rsid <rsid>
Example:
mycompanyid> set_rsid myprodrsid
Default RSID set to myprodrsid
mycompanyid:myprodrsid>
Display information about the currently authenticated user. Calls getUserMe().
whoami
Clear the terminal screen. Also available inside the RequestCreator sub-shell.
clear
Exit the CLI.
List all report suites accessible to the current company.
get_report_suites [-f filter] [-ext] [-sv file.csv]
Arguments:
-f: OPTIONAL : Filter by name substring.-ext: OPTIONAL : Include extended information.-sv: OPTIONAL : Save to CSV.
Get the full details for a single report suite. Uses the session RSID if no argument is passed.
get_report_suite <rsid>
List all virtual report suites.
get_virtual_report_suites [-f filter] [-ext] [-sv file.csv]
Get the full details for a single virtual report suite.
get_virtual_report_suite <vrsid>
Create a virtual report suite from a JSON definition file.
The JSON file should contain the full VRS definition as expected by the Adobe Analytics API.
create_virtual_report_suite -d definition.json
Delete a virtual report suite. Prompts for confirmation.
delete_virtual_report_suite <vrsid>
Compare several report suites side-by-side for a given element type (dimensions, metrics, etc.).
compare_report_suites -rsids id1,id2,id3 [-el element] [-sv file.csv]
Arguments:
-rsids: REQUIRED : Comma-separated list of RSIDs to compare.-el: OPTIONAL : Element to compare (e.g.dimensions,metrics). Default isdimensions.-sv: OPTIONAL : Save the comparison to CSV.
List all dimensions for a report suite. Always saved to CSV as dimensions_<rsid>.csv unless -fn overrides the filename.
get_dimensions [-rsid id] [-f filter] [-fn file.csv]
List all metrics for a report suite. Always saved to CSV as metrics_<rsid>.csv unless -fn overrides the filename.
get_metrics [-rsid id] [-f filter] [-fn file.csv]
List all calculated metrics. Always saved to CSV as calculated_metrics.csv unless -fn overrides the filename.
get_calculated_metrics [-n name] [-f filter] [-fn file.csv]
Arguments:
-n: OPTIONAL : Exact name filter passed to the API.-f: OPTIONAL : Additional local substring filter.-fn: OPTIONAL : Override the default output CSV filename (the result is always saved).
Get full details for a single calculated metric.
get_calculated_metric <id>
Create a calculated metric from a JSON definition file.
create_calculated_metric -d definition.json
Update an existing calculated metric.
update_calculated_metric <id> -d definition.json
Delete a calculated metric. Prompts for confirmation.
delete_calculated_metric <id>
List all functions available in the metric builder.
get_calculated_functions [-sv file.csv]
Scan a calculated metric definition and report which components (segments, metrics) it references.
scan_calculated_metric <id> [-v]
List segments. Always saved to CSV as segments.csv unless -fn overrides the filename.
get_segments [-n name] [-rsid id] [-f filter] [-fn file.csv]
Get full details for a single segment.
get_segment <id> [-full]
-full includes the full segment definition container.
Create a segment from a JSON definition file.
create_segment -d definition.json
Update an existing segment.
update_segment <id> -d definition.json
Delete a segment. Prompts for confirmation.
delete_segment <id>
Scan a segment definition and report which components it references.
scan_segment <id> [-v]
List all date ranges.
get_date_ranges [-f filter] [-sv file.csv]
Get full details for a single date range.
get_date_range <id>
Create a date range from a JSON definition file.
create_date_range -d definition.json
Update an existing date range.
update_date_range <id> -d definition.json
Delete a date range. Prompts for confirmation.
delete_date_range <id>
List all tags.
get_tags [-sv file.csv]
Get details for a single tag.
get_tag <id>
List all tags attached to a specific component.
get_component_tags <componentId> -type <componentType>
Component type examples: segment, calculatedMetric, dateRange, project.
Search for components that carry specific tag names.
search_tags -n tagName1,tagName2 -type <componentType>
Create one or more tags from a JSON definition file.
create_tags -d definition.json
Delete a tag. Prompts for confirmation.
delete_tag <id>
List Workspace projects.
get_projects [-f filter] [-full] [-sv file.csv]
-full includes the full project definition for each result.
Get full details for a single project.
get_project <id>
Fetch full details for every project in the company.
Note: this call retrieves each project definition individually and can be slow on large accounts. A warning is displayed before the request is sent.
get_all_project_details [-f filter] [-sv file.csv]
Create a project from a JSON definition file.
create_project -d definition.json
Update an existing project.
update_project <id> -d definition.json
Delete a project. Prompts for confirmation.
delete_project <id>
Run a report from a saved JSON request file.
The terminal displays the top 10 rows. The full result is always saved to a CSV file.
get_report -d request.json [-rsid id] [-n rows] [-sv output.csv]
Arguments:
-d: REQUIRED : Path to the JSON report request file.-rsid: OPTIONAL : Override the RSID embedded in the request.-n: OPTIONAL : Maximum number of rows to retrieve. Default isinf(all rows).-sv: OPTIONAL : Output CSV filename. A timestamped name is generated automatically if omitted.
The JSON request file follows the Adobe Analytics API 2.0 report request format.
You can build one interactively with the RequestCreator sub-shell and save it with save.
mycompanyid:myprodrsid> get_report -d my_q1_report.json
Get the top-ranked values for a dimension.
get_top_items <dimension> [-rsid id] [-dr dateRange] [-n limit] [-sv file.csv]
Arguments:
dimension: REQUIRED : Dimension ID, e.g.variables/eVar1,variables/page.-rsid: OPTIONAL : Report suite (uses session default if set).-dr: OPTIONAL : Date range inYYYY-MM-DD/YYYY-MM-DDformat.-n: OPTIONAL : Number of items to return. Default is 10.-sv: OPTIONAL : Save results to CSV.
Example:
mycompanyid:myprodrsid> get_top_items variables/page -dr 2024-01-01/2024-01-31 -n 25
Decode Adobe Analytics image request URLs from a file.
decode_aa_requests -d file [-sv output.csv]
The request_creator command enters a dedicated sub-shell for building report requests interactively.
It wraps the RequestCreator class — every method on that class is available as a sub-command.
The session RSID is pre-loaded automatically when you enter the sub-shell.
mycompanyid:myprodrsid> request_creator
RequestCreator mode — type 'help' for commands, 'done' to return.
[request:myprodrsid]>
The prompt shows the current RSID. Type done or press Ctrl+D to return to the main shell.
-
set_rsid <rsid>
Set the report suite for this request. Also updates the sub-shell prompt. -
set_dimension <dimension>
Set the breakdown dimension, e.g.variables/eVar1. -
set_date_range <range>orset_date_range -d <days> [--start DATE | --end DATE]orset_date_range -id <dateRangeId>
Set (add or replace) the request's date range — the only command for this, replacing the oldupdate_date_range.<range>accepts either the full timeframe (2026-03-01T00:00:00.000/2026-03-31T23:59:59.999) or a simplified date-only version (2026-03-01/2026-03-31), which is automatically expanded to the full timeframe.Use
-d <n>instead to set the range tondays. Alone, it ends today (today and then-1days before it). Combine it with--start DATEto anchor the window's start and compute the end (start + n - 1days), or with--end DATEto anchor the end and compute the start (end - n + 1days).--startand--endcan also be combined without-dfor an explicit range.Use
-id <dateRangeId>instead to reference a saved/custom Date Range component (seeget_date_rangesin the main shell) rather than a literal range.[request:myprodrsid]> set_date_range 2026-03-01/2026-03-31 Date range set to: 2026-03-01T00:00:00.000/2026-03-31T23:59:59.999 [request:myprodrsid]> set_date_range -d 7 Date range set to: 2026-09-04T00:00:00.000/2026-09-10T23:59:59.999 [request:myprodrsid]> set_date_range -d 5 --start 2026-03-01 Date range set to: 2026-03-01T00:00:00.000/2026-03-05T23:59:59.999 [request:myprodrsid]> set_date_range -id 586ac3ec71ade31753dc35d0 Date range set to: 586ac3ec71ade31753dc35d0 -
set_limit <n>
Set the number of result rows. Default is 100. -
set_repeat_instance <true|false>
Specify whether repeated instances should be counted. -
set_none_behavior <true|false>
Include or exclude None values in the results.
-
add_metric <metricId>
Add a metric to the request. Repeatable, e.g.add_metric metrics/visits. -
remove_metric <metricId>
Remove a specific metric from the request. -
remove_metrics
Remove all metrics from the request. -
get_report_metrics
List all metrics currently in the request.
Handy while building a request, to check what's actually available in the report suite before adding it.
Same behavior as their top-level counterparts: results are always saved to CSV (override the filename with -fn).
-
get_dimensions [-rsid id] [-f filter] [-fn file.csv]
List dimensions available for a report suite. Uses the sub-shell's current RSID if-rsidis omitted. -
get_metrics [-rsid id] [-f filter] [-fn file.csv]
List metrics available for a report suite. Uses the sub-shell's current RSID if-rsidis omitted.
Not to be confused withget_report_metrics, which lists the metrics already added to this request. -
get_calculated_metrics [-n name] [-f filter] [-fn file.csv]
List all calculated metrics. -
get_segments [-n name] [-rsid id] [-f filter] [-fn file.csv]
List segments. -
get_date_ranges [-f filter] [-fn file.csv]
List saved/custom date ranges. Grab anidfrom here to use withset_date_range -id <id>.
-
add_global_filter <id>
Add a global filter. Theidcan be a segment ID or a date range ID. -
remove_global_filter <id>
Remove a global filter by its ID. -
add_metric_filter <metricId> <filterId>
Attach a filter to a specific metric. -
set_search <clause>
Add a search clause to the request. -
remove_search
Remove the search clause. -
get_filters
List all global filters currently in the request.
-
show
Print the current request as formatted JSON. -
save [filename]
Save the request to a JSON file. A timestamped filename is generated if none is provided. -
load <filename>
Load a previously saved request from a JSON file, replacing the current state.
run
Execute the current request. Displays the top 10 rows in the terminal and saves the full result to a timestamped CSV file. The CSV filename is printed on completion.
Exit the RequestCreator sub-shell and return to the main shell.
mycompanyid:myprodrsid> request_creator
[request:myprodrsid]> set_dimension variables/eVar1
[request:myprodrsid]> add_metric metrics/visits
[request:myprodrsid]> add_metric metrics/pageviews
[request:myprodrsid]> add_global_filter s123456789
[request:myprodrsid]> update_date_range 2024-01-01/2024-03-31
[request:myprodrsid]> set_limit 50
[request:myprodrsid]> show
[request:myprodrsid]> save my_q1_report.json
[request:myprodrsid]> run
[request:myprodrsid]> done
mycompanyid:myprodrsid>
The saved JSON file can be reused at any time with get_report:
mycompanyid:myprodrsid> get_report -d my_q1_report.json -sv full_q1.csv
List all scheduled Workspace projects.
get_scheduled_jobs [-f filter] [-sv file.csv]
Get details for a single scheduled job.
get_scheduled_job <id>
Create a scheduled job for a project.
The JSON definition file should contain the schedule parameters (type, schedule, loginIds, emails, etc.).
create_scheduled_job -pid <projectId> -d definition.json
Update an existing scheduled job.
update_scheduled_job <id> -d definition.json
Delete a scheduled job. Prompts for confirmation.
delete_scheduled_job <id>
List all annotations.
get_annotations [-sv file.csv]
Get full details for a single annotation.
get_annotation <id>
Create an annotation from a JSON definition file.
The JSON file fields map to the createAnnotation() method parameters (name, dateRange, rsid, metricIds, etc.).
create_annotation -d definition.json
Update an existing annotation.
update_annotation <id> -d definition.json
Delete an annotation. Prompts for confirmation.
delete_annotation <id>
List all alerts.
get_alerts [-sv file.csv]
Get details for a single alert.
get_alert <id>
Enable an alert.
enable_alert <id>
Disable an alert.
disable_alert <id>
Delete an alert. Prompts for confirmation.
delete_alert <id>
Renew one or more alerts.
renew_alerts -ids id1,id2,id3
List all users in the company.
get_users [-f filter] [-sv file.csv]
Display information about the currently authenticated user. Also available as a session command at the top level.
whoami
Retrieve usage audit logs for a date range.
get_usage_logs -start YYYY-MM-DD -end YYYY-MM-DD [-login user] [-rsid id] [-sv file.csv]
Arguments:
-start: REQUIRED : Start date inYYYY-MM-DDformat.-end: REQUIRED : End date inYYYY-MM-DDformat.-login: OPTIONAL : Filter by user login.-rsid: OPTIONAL : Filter by report suite.-sv: OPTIONAL : Save results to CSV.
Example:
mycompanyid> get_usage_logs -start 2024-01-01 -end 2024-01-31 -login jpiccini -sv jan_logs.csv
List all classification datasets for a report suite.
get_classification_datasets [-rsid id] [-sv file.csv]
List classification jobs for a dataset.
get_classification_jobs <datasetId> [-n n_results]
Get details for a single classification job.
get_classification_job <jobId>
Download the classification template for a dataset.
get_classification_template <datasetId> [-sv file.csv]
Import classification data from a JSON file.
This uses the simpler single-call path (importClassificationJSON).
import_classification_json <datasetId> -d data.json [-n jobName]
Create a classification export job.
create_export_classification <datasetId> -n jobName [-d options.json]
Delete a classification dataset. Prompts for confirmation.
delete_classification <datasetId>
List all data feeds for a report suite.
get_data_feeds [-rsid id] [-sv file.csv]
Get details for a single data feed.
get_data_feed <id>
List data feed request runs.
get_data_feed_requests [-ids feedId1,feedId2] [-status status] [-sv file.csv]
Update a data feed from a JSON definition file.
update_data_feed <id> -d definition.json
List Data Warehouse scheduled requests.
get_dw_requests [-rsid id] [-sv file.csv]
Get details for a single scheduled DW request.
get_dw_request <id>
List Data Warehouse report runs.
get_dw_reports [-status status] [-sv file.csv]
List data source accounts for a report suite.
get_data_source_accounts [-rsid id] [-sv file.csv]
List jobs for a data source account.
get_data_source_jobs <accountId> [-rsid id] [-status status] [-sv file.csv]
These commands manage the cloud accounts and locations used for Data Warehouse and Data Feed delivery.
List all cloud accounts.
get_cloud_accounts [-type accountType] [-sv file.csv]
List all cloud locations.
get_cloud_locations [-sv file.csv]