Cato Networks GraphQL API CLI

catocli is a command-line client for the Cato Networks GraphQL API. It supports interactive use and automation for querying, reporting, and managing Cato account configuration.

Use it to:

Query network, security, user, and application data
Manage supported Cato configuration through GraphQL mutations
Export results as JSON or CSV
Automate workflows with profiles, files, and command-line overrides

Requirements

Python 3.10 or newer (tested with Python 3.10 through 3.14)
A Cato API token and account ID

See Generating API Keys for the Cato API for token setup.

Installation

python3 -m pip install --upgrade catocli
catocli --version

Quick start

Configure the default profile:

# Interactive setup
catocli configure set

# Or non-interactive setup
catocli configure set --cato-token "your-api-token" --account-id "12345"

Run a query:

catocli query entityLookup '{"type":"country"}'

Inspect available commands and operation-specific arguments:

catocli --help
catocli query --help
catocli query entityLookup --help

Credentials are stored in the local profile configuration. Do not place API tokens in source files, shell history, or committed scripts. See Profile Management for named profiles and environment selection.

Configuration

# List profiles
catocli configure list

# Show the active profile
catocli configure show

# Select a profile
catocli configure use prod

# Override the configured account for one operation
catocli query entityLookup -accountID 12345 '{"type":"country"}'

For shell completion setup, see Tab Completion.

JSON input

Pass variables inline or load them from a file:

catocli query site networkRangeList \
  '{"networkRangeListInput":{"site":{"by":"ID","input":"527548"}}}'

catocli query site networkRangeList \
  --json-file query.site.networkRangeList.json

Operation help includes a generated input example:

catocli query site networkRangeList --help

Run from source

git clone https://github.com/Cato-Networks/cato-cli.git
cd cato-cli
python3 -m catocli --help

Guides

Common Patterns and Best Practices: output formats, time frames, and filtering
Python Integration on Windows
Python Integration on Unix, Linux, and macOS
SIEM Integration: real-time security event streaming
Terraform Rules Integration: policy export and import for infrastructure as code

Reporting guides

Account Metrics: network performance by site, user, or interface
Application Statistics: user and application activity
Application Statistics Time Series: traffic over time
Events Time Series: security, connectivity, and threat events
Socket Port Metrics: socket interface performance
Socket Port Time Series: socket performance over time

Examples

Account metrics

catocli query accountMetrics '{"timeFrame":"last.PT1H"}'

User activity CSV

catocli query appStats '{
    "appStatsFilter": [],
    "appStatsSort": [],
    "dimension": [ { "fieldName": "user_name" }, { "fieldName": "domain" } ],
    "measure": [
        { "aggType": "sum", "fieldName": "upstream" },
        { "aggType": "sum", "fieldName": "downstream" },
        { "aggType": "sum", "fieldName": "traffic" },
        { "aggType": "sum", "fieldName": "flows_created" }
    ],
    "timeFrame": "last.P1D"
}' -f csv --csv-filename appStats_daily_user_activity_report.csv

Security event analysis

catocli query eventsTimeSeries '{
    "buckets": 7,
    "eventsFilter": [{"fieldName": "event_type", "operator": "is", "values": ["Security"]}],
    "eventsMeasure": [{"aggType": "sum", "fieldName": "event_count"}],
    "perSecond": false,
    "timeFrame": "last.P7D"
}' -f csv --csv-filename eventsTimeSeries_weekly_security_events_report.csv

Output formats

Reporting operations support:

Enhanced JSON output by default
Original API JSON with --raw
CSV output with -f csv
Custom filenames with --csv-filename
Timestamped filenames with --append-timestamp

Check operation help before using format-specific options:

catocli query appStats --help

Time frames

Common time frame patterns:

last.PT1H: last hour
last.P1D: last day
last.P7D: last seven days
last.P1M: last month
utc.2026-08-{01/00:00:00--01/23:59:59}: custom UTC range

Getting Help

Add -h or --help to any command
Read the Cato API documentation
Verify installed versions with catocli --version and python3 --version
Download Python from python.org

License

See LICENSE.

Release files for catocli 3.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for catocli 3.1.2
File	Size	Uploaded
catocli-3.1.2.tar.gz	19.3 MB	Aug 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for catocli 3.1.2
File	Interpreter	ABI	Platform	Reset
catocli-3.1.2-py3-none-any.whl 21.2 MB Aug 26, 2026	Python 3	none	any	Details

Total release size: 40.5 MB

Release files / catocli-3.1.2.tar.gz

Download URL	catocli-3.1.2.tar.gz
Size	19.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`6c43593a3a821b9e0703e32be88eff9ef276a101cd81ed7e706adc6ebe439329`
BLAKE2b-256 checksum How to use checksums	`52c31ddeff087d49da33df17a2ef491d6b3d70bbba4b35d35b0df1aa53a9d98f`
Upload date	Aug 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/catonetworks/cato-cli
Publishing commit: github.com/catonetworks/cato-cli/tree/13c46ff863530dd61f93ca3778b23b61981d2adb

Workflow

Publishing configuration: github.com/catonetworks/cato-cli/blob/13c46ff863530dd61f93ca3778b23b61981d2adb/.github/workflows/publish-to-pypi.yml
Publishing logs: github.com/catonetworks/cato-cli/actions/runs/32965941356/attempts/1

Artifact

Subject: catocli-3.1.2.tar.gz
SHA-256 checksum: 6c43593a3a821b9e0703e32be88eff9ef276a101cd81ed7e706adc6ebe439329 Verifying attestations

Release files / catocli-3.1.2-py3-none-any.whl

Download URL	catocli-3.1.2-py3-none-any.whl
Size	21.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`ef03e2dda42c10729e7ede55414bc301f0ba4d47cd5f2186db700701e53ff9fd`
BLAKE2b-256 checksum How to use checksums	`064e7e2d7d3730fd62295bdd14b9263e54c03c5877a833d25e1034daf7ed4cff`
Upload date	Aug 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/catonetworks/cato-cli
Publishing commit: github.com/catonetworks/cato-cli/tree/13c46ff863530dd61f93ca3778b23b61981d2adb

Workflow

Publishing configuration: github.com/catonetworks/cato-cli/blob/13c46ff863530dd61f93ca3778b23b61981d2adb/.github/workflows/publish-to-pypi.yml
Publishing logs: github.com/catonetworks/cato-cli/actions/runs/32965941356/attempts/1

Artifact

Subject: catocli-3.1.2-py3-none-any.whl
SHA-256 checksum: ef03e2dda42c10729e7ede55414bc301f0ba4d47cd5f2186db700701e53ff9fd Verifying attestations