Skip to main content

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.11 through 3.15)
  • 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

Reporting guides

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

Regenerating GraphQL commands

Run python schema/regenerate.py from the repository root to rebuild models, payloads, parsers, READMEs, and generated query test inputs from the checked-in schema/introspection.json. This does not download a new schema or location data.

Namespace types with argument-free fields belong in childOperationObjects in catocli/clisettings.json so each operation gets its own command. For example, RBAC commands use catocli mutation rbac roleManagement createRole and catocli query rbac roleManagement permissionCatalog.

The weekly Jenkins job also rebuilds siteLocation.db and its JSON export from GeoNames cities, countries, and administrative regions plus ISO subdivision data. Time zones are refreshed with the city records. These reference-data changes are included in the generated pull request even when the GraphQL schema is unchanged. SKIP_SITE_LOCATION_UPDATE=true skips these downloads for schema-only imports; the offline regeneration command above always uses the saved schema and data.

For generated operations with an Upload input, pass a local file path in that input. The CLI sends the file using GraphQL multipart upload. Combined file contents are limited to 32 MiB per request. The -t option prints the query without opening or uploading files.

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.

Metadata

Release files for catocli 3.2.5

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.2.5
File Size Uploaded Provenance Actions
catocli-3.2.5.tar.gz 21.2 MB With provenance Details for catocli-3.2.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for catocli 3.2.5
File Interpreter ABI Platform Actions
catocli-3.2.5-py3-none-any.whl Python 3 none any Details for catocli-3.2.5-py3-none-any.whl

Total release size: 43.7 MB

Release files / catocli-3.2.5.tar.gz

Download URL catocli-3.2.5.tar.gz
Size 21.2 MB
Tags Source
SHA-256 checksum
How to use checksums
ee309e84649f1113619ed1d709451ae3f65ab85fdbd84bb06246f6209c5035b1
BLAKE2b-256 checksum
How to use checksums
48fea839f94f2f69ef7ce7a77f592c4bf8265256ba28e312d5e98d0f4df72396
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

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

Download URL catocli-3.2.5-py3-none-any.whl
Size 22.5 MB
Tags Python 3
SHA-256 checksum
How to use checksums
a20d44a3d4baf95b097f5354ee0f530cbc12ef92aa21f6f3735eecd337798283
BLAKE2b-256 checksum
How to use checksums
b6f81e5c8a9ff7a28ac3a7bac654d9fb3c67a7aaa3ed27ab4182bd7a44c092fb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for catocli 3.2.5

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for catocli-3.2.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.2.5 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page