Cato Networks GraphQL API CLI

The package provides a simple to use CLI that reflects industry standards (such as the AWS cli), and enables customers to manage Cato Networks configurations and processes via the Cato Networks GraphQL API easily integrating into configurations management, orchestration or automation frameworks to support the DevOps model.

Overview

CatoCLI is a command-line interface that provides access to the Cato Networks GraphQL API, enabling you to:

Generate detailed network and security reports
Analyze user and application activity
Monitor network performance and events
Export data in multiple formats (JSON, CSV)
Automate reporting and monitoring tasks

Prerequisites

Python 3.6 or higher
CatoCLI installed (pip3 install catocli)
Valid Cato Networks API token and Account ID
Proper authentication configuration (see Authentication Setup)

Installation

pip3 install catocli

Authentication Setup

Configure your CatoCLI profile before using any query operations:

# Interactive configuration
catocli configure set

# Non-interactive configuration
catocli configure set --cato-token "your-api-token" --account-id "12345"

# List configured profiles
catocli configure list

# Show current profile
catocli configure show

Enable cli tab auto-completion

For detailed information about enabling tab completion, see TAB_COMPLETION.md.

Documentation

For detailed information about profile management, see PROFILES.md.

CLICK HERE to see how create an API key to authenticate.

Running the CLI

catocli -h
catocli query -h
catocli query entityLookup -h
catocli query entityLookup '{"type":"country"}`

// Override the accountID value as a cli argument
catocli query entityLookup -accountID=12345 '{"type":"country"}`

Check out run locally not as pip package

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

Advanced cato-cli Topics

Common Patterns & Best Practices - Output formats, time frames, filtering patterns
Python Integration - Windows - Windows-specific Python automation examples
Python Integration - Unix/Linux/macOS - Unix-based Python integration guide
SIEM Integration Guide - Real-time security event streaming to SIEM platforms
Terraform Rules Integration - Export/import policy rules to Terraform for IaC management

Custom Report Query Operations

Custom Report Analytics Queries

Operation	Description	Guide
Account Metrics	Network performance metrics by site, user, or interface	📊
Application Statistics	User activity and application usage analysis	📱
Application Statistics Time Series	Traffic analysis over time with hourly/daily breakdowns	📈
Events Time Series	Security events, connectivity, and threat analysis	🔒
Socket Port Metrics	Socket interface performance and traffic analysis	🔌
Socket Port Time Series	Socket performance metrics over time	⏱️

Quick Start Examples

Basic Network Health Check

# Get last hour account metrics
catocli query accountMetrics '{"timeFrame":"last.PT1H"}'

User Activity Report (csv format)

# Export user activity for the last month to 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 Events Analysis

# Weekly security events breakdown
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

CatoCLI supports multiple output formats:

Enhanced JSON (default): Formatted with granularity adjustments
Raw JSON: Original API response with -raw flag
CSV: Structured data export with -f csv
Custom CSV: Named files with --csv-filename and --append-timestamp

Time Frame Options

Common time frame patterns:

last.PT1H - Last hour
last.P1D - Last day
last.P7D - Last week
last.P1M - Last month
utc.2023-02-{28/00:00:00--28/23:59:59} - Custom UTC range

Getting Help

Use -h or --help with any command for detailed usage
Check the Cato API Documentation
Review individual operation guides linked above

This CLI is a Python 3 application and has been tested with Python 3.6 -> 3.8

Requirements:

python 3.6 or higher

Confirm your version of python if installed:

Open a terminal
Enter: python -V or python3 -V

Installing the correct version for environment:

https://www.python.org/downloads/

Release files for catocli 3.1.1

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.1
File	Size	Uploaded
catocli-3.1.1.tar.gz	19.3 MB	Aug 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for catocli 3.1.1
File	Interpreter	ABI	Platform	Reset
catocli-3.1.1-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.1.tar.gz

Download URL	catocli-3.1.1.tar.gz
Size	19.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`1b0ce14498823828f6524951c0166cfe1fe601ebca6df107ce853dc35c3f8b4b`
BLAKE2b-256 checksum How to use checksums	`72ca5c9081beebc16dd53264e3d11de53ca71b45707880f2c7db43ed7fabb60b`
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/88484e7ff95be46b759ae3a08e002fbe040dfc8a

Workflow

Publishing configuration: github.com/catonetworks/cato-cli/blob/88484e7ff95be46b759ae3a08e002fbe040dfc8a/.github/workflows/publish-to-pypi.yml
Publishing logs: github.com/catonetworks/cato-cli/actions/runs/32946358372/attempts/1

Artifact

Subject: catocli-3.1.1.tar.gz
SHA-256 checksum: 1b0ce14498823828f6524951c0166cfe1fe601ebca6df107ce853dc35c3f8b4b Verifying attestations

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

Download URL	catocli-3.1.1-py3-none-any.whl
Size	21.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`2467caeaf41a48b8e2d0f70ef41288818f2b0c9397596ff4f054f8413373831f`
BLAKE2b-256 checksum How to use checksums	`d53ea47fd1ff6e5f0b246c9c444e415c1f9ef3e901e0f584fad1a4ffb4e61196`
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/88484e7ff95be46b759ae3a08e002fbe040dfc8a

Workflow

Publishing configuration: github.com/catonetworks/cato-cli/blob/88484e7ff95be46b759ae3a08e002fbe040dfc8a/.github/workflows/publish-to-pypi.yml
Publishing logs: github.com/catonetworks/cato-cli/actions/runs/32946358372/attempts/1

Artifact

Subject: catocli-3.1.1-py3-none-any.whl
SHA-256 checksum: 2467caeaf41a48b8e2d0f70ef41288818f2b0c9397596ff4f054f8413373831f Verifying attestations