Netskope CLI — Complete Guide

Installation

Choose any method below. The CLI installs as both netskope and the shorter alias ntsk.

Recommended

pipx (isolated install)

# Install pipx first if needed
$ brew install pipx && pipx ensurepath  # macOS
$ python3 -m pip install --user pipx     # Linux

# Then install Netskope CLI
$ pipx install netskope

pip (all platforms)

$ pip install netskope

uv (isolated install)

$ uv tool install netskope   # netskope and ntsk on your PATH
$ uvx netskope --help         # or run once without installing

Homebrew (macOS / Linux)

$ brew tap netskopeoss/tap
$ brew install netskope

From source

$ git clone https://github.com/netskopeoss/netskope-cli.git
$ cd netskope-cli
$ pip install .

Verify installation

$ ntsk --version
netskope-cli 1.5.1
$ ntsk --help

Requires Python 3.11+ and a Netskope tenant with API access.

Getting Started

Three steps to go from install to your first query.

1

Configure your tenant

Run the interactive setup wizard, or set the tenant hostname manually.

# Option A: Interactive wizard (recommended)
$ ntsk config setup

# Option B: Set tenant directly
$ ntsk config set-tenant mytenant.goskope.com

Config is stored at ~/.config/netskope/config.toml (XDG-compliant).

2

Authenticate

Choose between an API token or browser-based SSO login.

API Token Recommended

          # Via environment variable
$ export NETSKOPE_API_TOKEN="your-token"

# Or store securely in keyring
$ ntsk config set-token
        

Browser SSO

          # Opens browser for SSO login
$ ntsk auth login

# Check auth status
$ ntsk auth status
        

3

Start using the CLI

Verify your setup and run your first queries.

# Verify setup and connectivity
$ ntsk doctor
Netskope CLI Doctor

  ✓ Config file exists: ~/.config/netskope/config.toml
  ✓ Active profile: default
  ✓ Tenant configured: https://sedemo.goskope.com
  ✓ API token: set (source: NETSKOPE_API_TOKEN env var)
  • Session cookie: not set (optional)
  ✓ CA bundle: /usr/lib/ssl/cert.pem
  ✓ API connectivity: OK

  All checks passed! You're good to go.

# List recent alerts
$ ntsk alerts list --since 24h --limit 5
5 results
Time range: 2026-02-24 23:11 UTC → 2026-02-24 23:11 UTC
                              Alerts
┏━━━━━━━━━━━━━━━━━━━━━━━━━⓿━━━━━━━━━━━━━━━━━━━━━⓿━━━━━━━━━⓿━━━━━━━━━━━━━━━━━━━━┓
┃ alert_name              ┃ alert_type          ┃ app     ┃ timestamp            ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━┩
┃ Session timeout for ... ┃ Security Assessment ┃ Workday ┃ 2026-02-24 23:11 UTC ┃
┃ Integration System ...  ┃ Security Assessment ┃ Workday ┃ 2026-02-24 23:11 UTC ┃
┃ Sensitive data should.. ┃ Security Assessment ┃ Workday ┃ 2026-02-24 23:11 UTC ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━┛

AI Agent Skill

Claude Code / AI agent prompt for operating the CLI

This is a ready-to-use Claude Code skill that teaches an AI agent how to use every netskope CLI command. Copy the text below and save it as .claude/commands/netskope.md in your project to enable the /netskope slash command.

netskope.md Claude Code Skill

Click to expand

Usage: After saving the file, type /netskope followed by your request in Claude Code. For example:

/netskope show me high severity alerts from the last 24 hours
/netskope investigate user alice@example.com
/netskope export application events from last 7 days as CSV

Agent discovery: Run ntsk commands --flat --json to get all commands with "mode": "read"|"write" tags and "supports_yes_flag" metadata. Commands tagged [write] modify tenant state — pass --yes to skip confirmation prompts.

Architecture

How the CLI is structured internally — from command entry to API response.

Request Flow

flowchart LR A["User
ntsk alerts list"] --> B["main.py
Typer App
Global Options"] B --> C["Command Module
alerts_cmd.py
Build params"] C --> D["NetskopeClient
client.py
Async httpx"] D --> E["Netskope API
api/v2/..."] E --> F["OutputFormatter
output.py
Unwrap & format"] F --> G["Terminal
table / json / csv"] style A fill:#dbeafe,stroke:#2563eb,color:#1e3a5f style B fill:#f1f5f9,stroke:#94a3b8,color:#0f172a style C fill:#f1f5f9,stroke:#94a3b8,color:#0f172a style D fill:#ede9fe,stroke:#8b5cf6,color:#3b0764 style E fill:#dcfce7,stroke:#22c55e,color:#14532d style F fill:#f1f5f9,stroke:#94a3b8,color:#0f172a style G fill:#fef3c7,stroke:#f59e0b,color:#78350f

Configuration Resolution

flowchart TD A["CLI Flag
--profile, -o"] --> E{Resolved Value} B["Env Var
NETSKOPE_*"] --> E C["Profile Config
config.toml"] --> E D["Defaults
table, default"] --> E E --> F["Used by Command"] style A fill:#fee2e2,stroke:#ef4444,color:#7f1d1d style B fill:#fef3c7,stroke:#f59e0b,color:#78350f style C fill:#dbeafe,stroke:#2563eb,color:#1e3a5f style D fill:#f1f5f9,stroke:#94a3b8,color:#334155 style E fill:#dcfce7,stroke:#22c55e,color:#14532d style F fill:#f1f5f9,stroke:#94a3b8,color:#0f172a

Highest priority wins: CLI flags > env vars > profile config > defaults.

Core Modules

main.py Entry point. State dataclass, global option hoisting, Typer app with lazy-loaded command groups.

client.py Async httpx client. Token & session auth, pagination, SSL/TLS CA bundle, typed error mapping.

config.py XDG-compliant TOML config. Multi-profile support, keyring credential storage, CA bundle auto-detection.

output.py OutputFormatter — json/table/csv/yaml/jsonl. Auto-unwraps API envelopes, TTY detection, timestamp conversion.

exceptions.py NetskopeError base with typed subclasses: AuthError, NotFoundError, RateLimitError, SSLError, etc.

Command Pattern

Every command module follows this consistent pattern:

      # Every command follows the same structure:
@app.command()
def list(ctx: typer.Context, query: str = None, limit: int = 25):
    state  = ctx.obj                     # Global State dataclass
    client = _build_client(ctx)          # Create NetskopeClient from config
    data   = client.request("GET", "/api/v2/...", params={...})
    fmt    = _get_formatter(ctx)         # Create OutputFormatter
    fmt.format_output(data, fmt=state.output.value, fields=...)

    

Configuration

Multi-profile TOML configuration with secure credential storage.

Config file layout

~/.config/netskope/config.toml — Permissions: 0600

        # Global settings
active_profile = "production"
output_format  = "table"
no_color       = false

# Default profile
[profiles.default]
tenant    = "dev.goskope.com"
auth_type = "token"

# Production profile
[profiles.production]
tenant    = "prod.goskope.com"
auth_type = "session"
ca_bundle = "/etc/ssl/netskope-ca.pem"
      

XDG directories

Purpose	Path
Config	`~/.config/netskope/config.toml`
Cache	`~/.cache/netskope/`
Data	`~/.local/share/netskope/`
Session cookies	`~/.local/share/netskope/session_{profile}.json`

All directories are created with 0700 permissions. Respects $XDG_CONFIG_HOME, $XDG_CACHE_HOME, and $XDG_DATA_HOME.

Profile management commands

# Create a new profile
$ ntsk config create-profile staging

# Set tenant for a specific profile
$ ntsk config set-tenant staging.goskope.com --profile staging

# Store API token securely in system keyring
$ ntsk config set-token --profile staging

# Switch the active profile
$ ntsk config use-profile staging

# List all profiles
$ ntsk config profiles

# Show effective config with resolution sources
$ ntsk config show
            Configuration — profile 'default'
┏━━━━━━━━━━━⓿━━━━━━━━━━━━━━━━━━━━⓿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Key       ┃ Value              ┃ Source                       ┃
┣━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
┃ profile   ┃ default            ┃ config                       ┃
┃ tenant    ┃ sedemo.goskope.com ┃ env var (NETSKOPE_TENANT)    ┃
┃ token     ┃ cmJh****eg==       ┃ env var (NETSKOPE_API_TOKEN) ┃
┃ auth_type ┃ token              ┃ config                       ┃
┗━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

# Test API connectivity
$ ntsk config test

Credential storage priority

System keyring (macOS Keychain, GNOME Keyring, Windows Credential Manager) — preferred and most secure
Plaintext in config file — automatic fallback when keyring is unavailable (file has 0600 perms)
Environment variable NETSKOPE_API_TOKEN — overrides both of the above

Authentication

Two methods: API token (stateless) or browser SSO session (cookie-based).

Auth Flow

flowchart TD A{Auth Method?} -->|API Token| B["Set Netskope-Api-Token header"] A -->|Browser SSO| C["ntsk auth login
Opens Chromium"] C --> D["User completes SSO/MFA"] D --> E["Capture ci_session cookie"] E --> F["Validate via /api/v2/rbac/roles/me"] F --> G["Save to keyring/file"] B --> H["API Request"] G --> H style A fill:#dbeafe,stroke:#2563eb,color:#1e3a5f style C fill:#ede9fe,stroke:#8b5cf6,color:#3b0764 style F fill:#dcfce7,stroke:#22c55e,color:#14532d style H fill:#f1f5f9,stroke:#94a3b8,color:#0f172a

API Token Auth

✓ Stateless, works in CI/CD pipelines
✓ Set once, works everywhere
✓ Scoped to specific API endpoints
• Token created in Netskope admin UI or via ntsk tokens create

        # Three ways to provide the token:
$ export NETSKOPE_API_TOKEN="your-token"
$ ntsk config set-token    # interactive prompt
$ echo "token" | ntsk config set-token  # piped
      

Browser SSO Auth

✓ Works with any SSO provider (Okta, Azure AD, etc.)
✓ Supports MFA/FIDO2
✓ Session saved per-profile
• Requires Playwright: pip install playwright && playwright install chromium

        $ ntsk auth login
Opening browser for SSO login...
✓ Authenticated successfully
  Session saved for profile 'default'

$ ntsk auth status
$ ntsk auth logout  # clear credentials
      

Output Formats

Five formats via -o / --output. Auto-detects TTY — table for terminals, JSON when piped.

Default in TTY -o table

Rich-formatted table with colored headers. Auto-selects the most informative columns when there are more than 10. Use -W for all columns.

$ ntsk publishers list --limit 3
Showing 3 of 7 results
                              Publishers
┏━━━━━━━━━━━━⓿━━━━━━━━━━━━━━⓿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━⓿━━━━━━━━━━━┓
┃ apps_count ┃ publisher_id ┃ publisher_name              ┃ status    ┃
┣━━━━━━━━━━━━╋━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━┩
┃ 6          ┃ 109          ┃ flonkerton-sedemo-publisher ┃ connected ┃
┃ 18         ┃ 126          ┃ NPA-Unified-Pub-US-EAST-1   ┃ connected ┃
┃ 7          ┃ 134          ┃ NPA-Unified-Pub-US-WEST-1   ┃ connected ┃
┗━━━━━━━━━━━━┷━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━┛

Default when piped -o json

Pretty-printed JSON. Ideal for jq pipelines and programmatic consumption. Adds ISO 8601 companion fields for timestamps.

$ ntsk users list -o json --limit 2
[
  {
    "id": "user-123",
    "userName": "alice@example.com",
    "email": "alice@example.com",
    "active": true,
    "givenName": "Alice",
    "familyName": "Smith",
    "parentGroups": ["Engineering", "All Users"],
    "provisioner": "SCIM"
  },
  ...
]

-o csv

Comma-separated values. Great for spreadsheets and data analysis. Nested objects are JSON-serialized.

$ ntsk alerts list -o csv --limit 3
alert_name,alert_type,app,severity,timestamp,user
Google Gmail watchlist,watchlist,Google Gmail,unknown,1769902541,n.rowe9631@gmail.com
OTP authentication grace period...,Security Assessment,Workday,,1766610188,
Session timeout for Workday...,Security Assessment,Workday,,1766610188,

-o yaml

YAML output. Readable for complex nested structures.

$ ntsk alerts list -o yaml --limit 1
- _id: 78047ceab1dd866c98ae76c0
  access_method: Client
  alert_name: Google Gmail watchlist
  alert_type: watchlist
  app: Google Gmail
  app_tags:
  - Enterprise
  - IP_Restrict
  appcategory: Webmail
  cci: 87
  ccl: high
  domain: mail.google.com
  dst_country: CA
  dstip: 192.178.192.17

-o jsonl

JSON Lines — one JSON object per line. Ideal for streaming large datasets and log processing.

$ ntsk alerts list -o jsonl --limit 2
{"_id":"09c94dc1...","alert_name":"OTP authentication grace period...","alert_type":"Security Assessment","app":"Workday","timestamp":1770900175,"timestamp_iso":"2026-02-12T12:42:55Z"}
{"_id":"43973c77...","alert_name":"Session timeout for Workday...","alert_type":"Security Assessment","app":"Workday","timestamp":1770900175,"timestamp_iso":"2026-02-12T12:42:55Z"}

Auto-unwrapping

Netskope API responses wrap data in envelopes (result, data, Resources). The formatter automatically extracts the actual records.

Timestamp conversion

Epoch timestamps are auto-converted to human-readable format in tables, and get ISO 8601 companion fields (*_iso) in JSON/CSV/YAML. Use --epoch to keep raw values.

TTY detection

Interactive terminal → table with colors. Piped output → JSON without colors. Spinners auto-suppressed when piped. Override with -o flag.

Global Flags

These flags work with every command and can appear before or after the subcommand.

Flag	Type	Description
`--profile NAME`	string	Configuration profile to use. Overrides `NETSKOPE_PROFILE` env var and `active_profile` in config. Default: `default`.
`-o, --output FORMAT`	enum	Output format: `json` \| `table` \| `csv` \| `yaml` \| `jsonl`. Default: `table` (TTY) or `json` (piped).
`-v, --verbose`	count	Increase verbosity. `-v` for info messages, `-vv` for debug (shows API request details).
`-q, --quiet`	flag	Suppress spinners and info messages. Only data and errors printed. Auto-enabled when piped.
`-W, --wide`	flag	Show all table columns without truncation. Also settable via `NETSKOPE_WIDE=1`.
`--raw`	flag	Include internal `_`-prefixed fields in output. By default these are stripped (except `_id`).
`--epoch`	flag	Keep timestamps as raw Unix epoch integers. Suppresses ISO 8601 companion fields.
`--count`	flag	Print only the record count. Endpoints that return a total report it. The `events`/`alerts`/`incidents` datasearch commands fetch one API page (10,000 rows, the datasearch cap) and print `N+` with a stderr notice when it fills up (`-o json`/`jsonl`/`csv`/`yaml` and any piped output print the bare integer, a lower bound). Elsewhere, including `events audit` and `events transaction`, the count is of the rows `--limit` fetched. Combined with `--group-by` it is the number of groups.
`--exact`	flag	With `--count` and `--start` on `events`/`alerts`/`incidents`: page through the API in 10,000-row steps for the true total, applying `--where` per page. Stops at `NETSKOPE_COUNT_CEILING` rows (default 200,000) and prints `N+` if reached. Can issue many requests. Datasearch endpoints only: `events audit`, `infrastructure` and `transaction` count a single page and say so.
`--no-color`	flag	Disable colored output. Also set via `NO_COLOR` env var.
`--version`	flag	Print version and exit.
`-f, --fields A,B`	string	Pick output fields on any command, in the order given. Dotted paths (`host_info.os`), list hops (`protocols[].port`), globs (`epdlp.*`). A name no record has warns with close matches and renders blank/null. See Querying Results.
`--list-fields`	flag	Run the command, then print every field in the response (nested paths, type, presence %, sample, default-column marker) instead of the records. `-o json` for a machine-readable schema.
`--where 'EXPR'`	string	Client-side row filter in JQL syntax: `eq ne gt ge lt le in like between`, `and/or/not`, parentheses, dotted paths. Runs before `--count`. Syntax errors exit 2 before any API call.
`--sort FIELD[:desc]`	string	Client-side stable sort on any path (comma-separate several keys). Missing values sort last.

Flag position flexibility

Global flags can appear before or after the subcommand. These are equivalent:

      $ ntsk -o json alerts list --limit 5
$ ntsk alerts list -o json --limit 5   # same result
    

One rule keeps this unambiguous: a global flag is only moved in front of the subcommand when the subcommand does not declare the same flag itself. So dem sites summary --where is still the DEM JSON where-clause and atp scan-file -f still means --file. Server-side field projections have their own name, --api-fields, so --fields, --where, --sort and --list-fields are always the client-side query options.

Querying Results: Discover, Select, Filter, Sort

Four global options that work on every command. They run on the rows the command fetched (so --limit still applies), never change the API request, and print all hints on stderr so -o json | jq and -o csv > file stay clean. Run ntsk docs fields for the in-terminal version of this page.

1

Discover — `--list-fields`

What fields does this response actually contain? Nested paths included, with type, how many records carry the field, a sample value, and * on the command's default columns.

$ ntsk devices list --list-fields
  field                          type     present  sample          default
  hostname                       str      100%     LAPTOP-7Q2      *
  host_info.os                   str      100%     Windows
  host_info.mac_addresses        list[str] 98%     aa:bb:cc:...
  epdlp.criticalErrorsCount      str      61%      0
  on_premises_detail[].match_ip  str      12%      10.0.4.1
  last_event_timestamp           int      100%     1756412345      *
  63 fields across 25 records · pick: --fields hostname,host_info.os · filter: --where 'hostname eq "..."'

$ ntsk devices list --list-fields -o json   # {"field","type","present_pct","sample","in_default"}
$ ntsk devices list --raw --list-fields      # include internal _ fields

2

Select — `--fields` / `-f`

Comma-separated paths, output in the order you give them, in every format. Unknown names print a warning with close matches instead of silently blanking a column. Quote globs in zsh.

$ ntsk devices list --fields hostname,host_info.os,host_info.os_version,last_event_timestamp
$ ntsk npa apps list --fields app_name,protocols[].port,service_publisher_assignments[].publisher_name -o csv
$ ntsk publishers list --fields 'publisher_name,assessment.version,capabilities.*'
$ ntsk devices list --fields hostnme
--fields: 'hostnme' not found in any record. Did you mean hostname, host_info.hostname? Run with --list-fields to see every field.

3

Filter — `--where`

The same JQL you already use with --query, evaluated locally on any command. Runs before --count, so the count is the filtered count.

$ ntsk devices list --where 'host_info.os like "win*" and epdlp.criticalErrorsCount gt 0'
$ ntsk publishers list --where 'status in ["disconnected","upgrading"]'
$ ntsk devices list --where 'idps eq null' --count
$ ntsk devices list --where 'hostname eq'
Error: Invalid --where expression: expected a value after 'eq'
    hostname eq
               ^
Hint: Run 'ntsk docs fields' for the --where syntax ...   (exit 2, no API call made)

4

Sort — `--sort`, and combine

Stable sort on any path, even one you do not display. Missing values sort last. Order of operations: --where → --count / --list-fields → --sort → --fields.

$ ntsk devices list --sort last_event_timestamp:desc --fields hostname,last_event_timestamp
$ ntsk devices list --sort host_info.os,hostname
$ ntsk devices list --where 'host_info.os like "mac*"' --sort hostname \
      --fields hostname,host_info.os_version -o csv > macs.csv

Path syntax	Meaning
`hostname`	Top-level key
`host_info.os`	Nested object key
`protocols[].port`	Every element of a list (`protocols.port` works too)
`protocols[0].port`	One element by index (negative indexes allowed)
`epdlp.` / `_timestamp`	Glob; expands to every matching leaf field. Brackets are literal.
`status.count`	A literal key containing a dot is tried first

`--where` rule	Behaviour
Strings	Case-insensitive; bare words need no quotes (`status eq connected`)
Numbers	Numeric strings compare as numbers; timestamps stay raw epoch ints
`like`	`*` and `?` wildcards, case-insensitive, brackets literal
Lists	A path that hits a list matches if any element matches; `ne` means no element matches
`eq null`	Matches null and missing fields
Precedence	`not` > `and` > `or`; use parentheses

Client-side vs server-side

Some commands also have server-side options, with distinct names, that change what the API returns: events/alerts/incidents --api-fields (server-side projection, top-level fields only; widened automatically with whatever --fields, --where and --sort reference, so a filter on a field you did not project still works) and --query (server-side JQL), dns/dspm/publishers --filter, dem ... --where (DEM JSON syntax), aicc ... --sort-by. Use the server-side option to fetch less, and the global ones to shape what came back — they combine: ntsk events alerts --query 'app eq "Slack"' --api-fields user,timestamp,app --where 'user like "*@corp.com"' --fields user,timestamp.

--count on those three groups fetches one API page (10,000 rows, the datasearch maximum) and prints 10000+ with a stderr notice when it filled up, instead of reporting the cap as the total (machine formats and piped output print the bare integer and keep the notice on stderr). Add --exact with --start to page for the true total (events audit states a total; infrastructure and transaction cannot be paged); ntsk status renders capped counts as ≥10,000 and sets alerts_capped: true in JSON.

Command Reference

25+ command groups covering the full Netskope platform. Run ntsk commands for the full tree.

Alerts

Get, list, filter, summarize security alerts

Events

Query 10 event types: alert, app, network, page, audit...

Incidents

Search, update, DLP forensics, notes, UCI scores

Users & Groups

User/group management with membership data

Policy

URL lists, policy deploy

Publishers

Manage publishers, upgrade profiles, local brokers

Services / CCI

Cloud Confidence Index, tags, private apps

Private Access (NPA)

Private apps, publishers, policy, tags, discovery

AI Command Center

AI apps, MCP servers, agents, models, identities, AI Risk Reports

Cloud Security

DSPM, SPM, RBI, ATP, IPS, Threat Intel

Infrastructure

Steering, devices, DNS, IPsec, enrollment

Monitoring

DEM (metrics, alerts, entities, apps, user/device telemetry), notifications, status, tokens

Utility

Doctor, tenant, docs, completion, commands

alerts

Security & Events

List and filter security alerts from the events datasearch API.

alerts list

Query GET /api/v2/events/datasearch/alert.

Option	Type	Default	Description
`--query`	string	—	JQL filter. E.g. `'alert_type eq "DLP"'`
`--api-fields`	string	—	Comma-separated top-level field list, sent to the API as a server-side projection and widened with whatever `--fields`/`--where`/`--sort` reference. Pick columns client-side (nested paths, globs) with the global `--fields`, see Querying Results
`-s, --start, --since`	string	—	Start time. Epoch or relative: `24h`, `7d`, `1h`
`-e, --end`	string	now	End time
`-l, --limit`	int	25	Max records
`-t, --type`	string	—	Filter by alert type (shortcut for `--query`)
`--group-by, --by`	string	—	Aggregate by field (e.g. `alert_type`, `severity`)
`--order-by`	string	—	Sort field
`--desc / --asc`	flag	—	Sort direction

# Recent DLP alerts as JSON
$ ntsk -o json alerts list --query 'alert_type eq "DLP"' --since 7d --limit 50

# Count alerts; a full 10,000-row API page is reported as a lower bound
$ ntsk alerts list --since 24h --count
10000+
Count capped at the 10,000 rows fetched; narrow the time range or use --exact.
$ ntsk alerts list --since 24h --count --exact
23871

# Only specific fields, sorted by timestamp
$ ntsk alerts list -f alert_name,severity,user,timestamp --order-by timestamp --desc

alerts get

Look up alerts by ID, user, app, name, or other fields. Queries GET /api/v2/events/datasearch/alert.

Option	Type	Default	Description
`ID` (positional)	string	—	Alert `_id` to look up (hex string)
`-u, --user`	string	—	Filter by user email
`-a, --app`	string	—	Filter by application name
`-n, --name`	string	—	Filter by alert name
`-t, --type`	string	—	Filter by alert type (DLP, malware, etc.)
`--severity`	string	—	Filter by severity (high, medium, low, critical)
`--activity`	string	—	Filter by activity type (e.g. Login Attempt)
`-s, --start, --since`	string	—	Start time. Epoch or relative: `24h`, `7d`
`-e, --end`	string	now	End time
`-l, --limit`	int	25	Max records (ignored for ID lookup)

# Look up a single alert by ID
$ ntsk alerts get f1c18fd0065a21e4ace54efb

# Find alerts for a specific user
$ ntsk alerts get --user alice@example.com --since 7d

# Filter by app and type
$ ntsk alerts get --app Slack --type DLP

# High severity login attempts
$ ntsk alerts get --severity high --activity "Login Attempt" --since 24h

# Combine multiple filters
$ ntsk -o json alerts get --user bob@company.com --type "Compromised Credential"

alerts summary

Aggregate alert counts by a grouping field.

Option	Description
`--by FIELD`	Field to group by: `alert_type`, `severity`, `user`, `app`, etc.
`-s, --start, --since`	Start time (relative or epoch)
`-e, --end`	End time

$ ntsk alerts summary --by alert_type
       Alert Summary by alert_type
┏━━━━━━━━━━━━━━━━━━━━━━━━⓿━━━━━━━┓
┃ alert_type             ┃ count ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━┩
┃ Security Assessment    ┃ 925   ┃
┃ policy                 ┃ 453   ┃
┃ watchlist              ┃ 163   ┃
┃ DLP                    ┃ 124   ┃
┃ AI Security            ┃ 37    ┃
┃ uba                    ┃ 15    ┃
┃ Compromised Credential ┃ 3     ┃
┃ Malware                ┃ 2     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━┛

alerts types

Lists all known Netskope alert types with descriptions. Useful for discovering valid --type filter values.

$ ntsk alerts types

events

Security & Events

Query security events by type. Ten event types available through a unified interface or individual subcommands.

Event Types

alert application network page incident audit infrastructure client-status epdlp transaction

Two equivalent approaches

          # Unified interface
$ ntsk events list --type application

# Direct subcommand (same result)
$ ntsk events application
        

events get

Look up events by ID, user, app, action, or other fields. Requires --type to specify the event category. API: GET /api/v2/events/datasearch/{type}

Option	Type	Default	Description
`ID` (positional)	string	—	Event `_id` to look up (hex string)
`-t, --type`	string	—	Event type (required)
`-u, --user`	string	—	Filter by user email
`-a, --app`	string	—	Filter by application name
`--action`	string	—	Filter by action (allow, block, alert)
`--severity`	string	—	Filter by severity level
`--policy`	string	—	Filter by policy name
`--domain`	string	—	Filter by domain name
`--srcip`	string	—	Filter by source IP
`--dstip`	string	—	Filter by destination IP
`--hostname`	string	—	Filter by device hostname
`-s, --start, --since`	string	—	Start time (epoch or relative)
`-e, --end`	string	now	End time
`-l, --limit`	int	25	Max records (ignored for ID lookup)

# Look up a single event by ID
$ ntsk events get abc123def456 --type alert

# Find application events for a user
$ ntsk events get --type application --user alice@example.com --since 7d

# Page events for a specific domain
$ ntsk events get --type page --domain github.com --since 24h

# Network events by source and destination IP
$ ntsk events get --type network --srcip 10.0.0.1 --dstip 192.168.1.1

# Blocked events for a specific app
$ ntsk -o json events get --type application --action block --app ChatGPT --since 7d

events list / events {type}

All event subcommands share these options. API: GET /api/v2/events/datasearch/{type}

Option	Type	Default	Description
`-t, --type`	string	—	Event type (required for `events list`)
`--query`	string	—	JQL filter expression
`--api-fields`	string	—	Comma-separated top-level field list, sent to the API as a server-side projection and widened with whatever `--fields`/`--where`/`--sort` reference. Pick columns client-side (nested paths, globs) with the global `--fields`, see Querying Results
`-s, --start`	string	—	Start time (epoch or relative)
`-e, --end`	string	now	End time
`-l, --limit`	int	25	Max records
`--group-by`	string	—	Aggregate by field
`--order-by`	string	—	Sort field
`--desc / --asc`	flag	—	Sort direction

# Page events with real response data
$ ntsk -o json events list --type page --limit 1
[
  {
    "access_method": "Client",
    "app": "iCloud Drive",
    "appcategory": "Cloud Storage",
    "cci": 56,
    "ccl": "low",
    "domain": "gateway.icloud.com",
    "dst_country": "US",
    "dst_location": "Cupertino",
    "netskope_pop": "US-SFO1",
    "os_family": "iOS",
    "srcip": "75.52.92.136",
    "user": "tandrey+web@netskope.com",
    "timestamp_iso": "2026-01-30T23:58:39Z"
  }
]

# Network events grouped by user
$ ntsk events network --group-by user --start 24h

# Application events as CSV
$ ntsk events application -o csv --start 7d > app_events.csv

incidents

Security & Events

View incidents, update status, retrieve DLP forensics, manage notes on DLP incidents, and check user confidence index.

incidents list / incidents search

API: GET /api/v2/events/datasearch/incident. list has optional query; search requires it.

Option	Type	Default	Description
`-q, --query`	string	—	JQL filter (required for `search`)
`--api-fields`	string	—	Comma-separated top-level fields, sent to the API and widened with whatever `--fields`/`--where`/`--sort` reference. Pick columns with the global `--fields`, see Querying Results
`-s, --start`	string	24h	Start time
`-e, --end`	string	now	End time
`-l, --limit`	int	100	Max records

$ ntsk incidents list --start 7d --limit 10
$ ntsk incidents search -q 'severity eq "critical"' --start 30d

incidents uci

Retrieve User Confidence Index (UCI) score. API: POST /api/v2/ubadatasvc/user/uci

$ ntsk incidents uci alice@example.com --from-time 30d

incidents update

Update one incident field (status, assignee or severity). API: PATCH /api/v2/incidents/update

            $ ntsk incidents update 1807262583165050077 --field status --new-value in_progress --user alice@example.com
          

incidents forensics & anomalies

            # DLP forensics for an incident
$ ntsk incidents forensics 32885923562112144

# UBA anomalies for a user
$ ntsk incidents anomalies --users alice@example.com
          

incidents notes

List, add, and delete analyst notes on a DLP incident. Each incident holds at most 25 notes of under 512 characters. API: /api/v2/incidents/dlpincidents/{id}/notes

            # List notes on a DLP incident
$ ntsk incidents notes list 1343008090332508247

# Add a note
$ ntsk incidents notes add 1343008090332508247 -c "Escalated to tier 2"

# Delete a note (prompts for confirmation; use --yes to skip)
$ ntsk incidents notes delete 1343008090332508247 <note-id> --yes
          

users

Policy & Access

User and group management with membership data. Query commands use the User Management API for rich data including group membership; CRUD commands use SCIM v2 for provisioning.

users list

API: POST /api/v2/users/getusers — Returns rich data including group membership (parentGroups).

Option	Type	Default	Description
`--filter`	JSON string	—	JSON filter dict. E.g. `'{"and": [{"emails": {"eq": "alice@example.com"}}]}'`
`--limit`	int	100	Max records to return (max 1000)
`--offset`	int	0	0-based pagination offset

$ ntsk -o json users list --limit 2
[
  {
    "id": "user-123",
    "userName": "alice@example.com",
    "email": "alice@example.com",
    "active": true,
    "givenName": "Alice",
    "familyName": "Smith",
    "parentGroups": ["Engineering", "All Users"],
    "provisioner": "SCIM"
  }
]

users get / create / update / delete

            # Look up user by email (auto-detected) or username
$ ntsk users get alice@example.com
$ ntsk users get alice --by username

# Create a new SCIM user
$ ntsk users create --username alice@example.com --email alice@example.com

# Update user (uses scimId from query results)
$ ntsk users update scim-uuid-... --set active=false

# Delete user
$ ntsk users delete scim-uuid-...
          

users groups (list / get / members / create / update / delete)

Query: POST /api/v2/users/getgroups — CRUD: /api/v2/scim/Groups

            # List groups with userCount and metadata
$ ntsk users groups list
$ ntsk users groups list --filter '{"deleted": {"eq": false}}'

# Look up group by display name
$ ntsk users groups get "Engineering"

# List all members of a group
$ ntsk users groups members "Engineering"

# SCIM CRUD
$ ntsk users groups create "Engineering" --members scimId1,scimId2
$ ntsk users groups update scim-group-id --name "New Name"
          

policy

Policy & Access

Manage URL lists and deploy pending policy changes.

policy url-list (list / create / get / update / delete)

API: /api/v2/policy/urllist

# List all URL lists
$ ntsk -o json policy url-list list
[
  {
    "id": 1,
    "name": "Exceptions to prohibited sites",
    "data": {
      "type": "exact",
      "urls": ["*.casino.com", "*.mansion.com", "casino.com"]
    },
    "modify_by": "twillis@netskope.com",
    "modify_time": "2024-06-03T23:54:03.000Z",
    "pending": 0
  },
  {
    "id": 3,
    "name": "YouTube Allowed",
    "data": { "urls": ["*youtube.com", "*.googlevideo.com"], "type": "exact" }
  }
]

# Create a new URL list
$ ntsk policy url-list create "Blocked Sites" --urls "malware.com,phishing.org"

# Deploy pending changes
$ ntsk policy deploy

publishers

Infrastructure

Manage private-access publishers, upgrade profiles, and local brokers. API: /api/v2/infrastructure/publishers

publishers list / get / create / update / delete

$ ntsk -o json publishers list --limit 2
[
  {
    "apps_count": 6,
    "publisher_id": 109,
    "publisher_name": "flonkerton-sedemo-publisher",
    "registered": true,
    "status": "connected",
    "stitcher_pop": "US-NYC1",
    "assessment": {
      "host_os_version": "Ubuntu 22.04.5 LTS",
      "ip_address": "10.0.0.17",
      "latency": 7,
      "version": "134.0.0.10606"
    }
  }
]

# Create a publisher
$ ntsk publishers create --name "prod-publisher-us-west"

# View upgrade profiles
$ ntsk publishers upgrade-profiles list

# List local brokers
$ ntsk publishers local-brokers list

services

Cloud Security

Cloud Confidence Index (CCI) lookups, service tags, publishers, and private apps.

services cci [APP_NAME]

Look up CCI risk data for a cloud application by exact name. Run without an argument for usage guidance. API: GET /api/v2/services/cci/app

$ ntsk -o json services cci "Slack"
[
  {
    "app_name": "Slack",
    "category_name": "Collaboration",
    "cci": 76,
    "ccl": "high",
    "id": 4877,
    "organisation": "Slack Technologies, LLC"
  }
]

Option	Description
`--category`	Filter by category
`--ccl`	Cloud Confidence Level: excellent, high, medium, low, poor
`--tag`	Filter by service tag
`--discovered`	Filter by discovery status

services tags / publishers / private-apps

            # Manage CCI service tags
$ ntsk services tags list
$ ntsk services tags create "Critical Apps"

# List publishers
$ ntsk services publishers list

# Private apps
$ ntsk services private-apps list
$ ntsk services private-apps create "Internal Wiki" --host wiki.internal
          

npa

Private Access

Netskope Private Access — comprehensive management of private apps, publishers, policy, tags, local brokers, and discovery.

Subcommand tree

npa apps

list / get / create / update / delete / bulk-delete / policy-check

npa publishers

list / get / create / delete / update / upgrade / releases / registration-token

npa publishers local-brokers

list / get / create / delete / update / config-get / config-update / registration-token

npa publishers upgrade-profiles

list / get / create / delete / update / assign

npa policy rules

list / get / create / update / delete

npa policy groups

list / get / create / update / delete

npa tags

list / get / create / update / delete / add / remove / replace / policy-check

npa app-publishers / discovery / alerts-config

add / remove / replace · get / update

        $ ntsk npa apps list --limit 10
$ ntsk npa policy rules list
$ ntsk npa policy rules get 42 --api-fields rule_name,enabled   # prints the rule object; --api-fields and --fields apply to its keys
$ ntsk npa publishers list
$ ntsk npa tags list
$ ntsk npa search "internal-wiki"
$ ntsk npa validate-name "my-new-app"
      

steering

Infrastructure

Manage private-app steering rules and global steering configuration.

      # View global steering config
$ ntsk steering config get

# Update steering settings
$ ntsk steering config update --set key=value

# List private apps in steering
$ ntsk steering private-apps list
$ ntsk steering private-apps get APP_ID
    

devices

Infrastructure

List managed devices, manage tags, and check supported OS versions. API: /api/v2/steering/devices

      $ ntsk devices list --limit 25
$ ntsk devices list --no-fallback          # disable v1 API fallback
$ ntsk devices list --list-fields          # see every field, whichever schema came back
$ ntsk devices list --fields hostname,host_info.os,last_event_timestamp --where 'host_info.os like "win*"'
$ ntsk devices supported-os

# Device tags management
$ ntsk devices tags list
$ ntsk devices tags create "Corporate Laptops"
$ ntsk devices tags delete TAG_ID
    

--no-fallback disables the automatic v1 API fallback. Note that the fallback schema may differ from the v2 response (different field names and structure) — run --list-fields to see exactly which fields you got, then pick them with the global --fields / --where.

aicc

AI Command Center

Discover and govern AI usage: inventories of AI applications, MCP servers, native agents, models, extensions, and the identities using them — with CCI risk scoring, usage analytics, alert posture, and one-command AI Risk Report data. Start with ntsk aicc guide for the built-in cheat sheet.

Orientation — start here

          $ ntsk aicc guide                              # data model + command map + recipes
$ ntsk aicc overview --start 30d              # entity counts + traffic/alert KPIs
$ ntsk aicc coverage                           # earliest date with data
        

Time flags accept 7d, 30d, ISO dates, or epochs (default: last 7 days). Check coverage before long windows — earlier start times return empty results.

AI Risk Report — AIRR data in one command

          # Full data bundle for report tooling
$ ntsk aicc report --start 30d > airr.json

# Rendered Markdown report for a fixed month
$ ntsk aicc report --start 2026-06-01 --end 2026-06-30 \
    --top 25 --format markdown --out airr.md
        

Aggregates ~10 endpoints: executive summary, top apps / MCP servers / users / unknown identities, alert posture, and computed key findings.

Inventories — apps, mcp, models, agents

          $ ntsk aicc apps list --sort-by bytes --limit 10
$ ntsk aicc apps list --status Unsanctioned --ccl Poor --ccl Low
$ ntsk aicc apps list --first-seen-after 30d   # what's new
$ ntsk aicc mcp list --sort-by sessions
$ ntsk aicc models list --deployment endpoint   # locally-run models
$ ntsk aicc agents list
        

Shared flags: --search, --limit/--offset, --all (fetch every page), --sort-by/--sort-dir; pick columns with the global --fields. CCI score (0–100) maps to CCL: Poor < Low < Medium < High < Excellent.

Drill-down — per-entity detail

          $ ntsk aicc apps get "Anthropic Claude"       # exact name from list
$ ntsk aicc apps status ChatGPT                # CASB sanctioning check
$ ntsk aicc apps identities ChatGPT --sort-by uploaded_bytes
$ ntsk aicc apps deployments ChatGPT --type cloud_web
$ ntsk aicc apps trend ChatGPT --kind traffic  # traffic|identity|risk
$ ntsk aicc apps violations ChatGPT --start 30d
        

Same verbs on mcp, models, agents, and extensions. Valid --type values for deployments come from footprint.types in the get output.

Identities — users & blind spots

          $ ntsk aicc identities list --type user --sort-by bytes
$ ntsk aicc identities list --type unknown --all  # unattributed sources
$ ntsk aicc identities get alice@example.com
$ ntsk aicc identities mcp alice@example.com       # also: models, agents, trend
        

Identity IDs are the user_id field — an email for users, an IP or hostname for unknown sources.

Analytics & DLP — KPIs, charts, alert posture

          $ ntsk aicc analytics entities                 # headline counts
$ ntsk aicc analytics sums traffic             # KPI + trend vs prior window
$ ntsk aicc analytics breakdown apps -d status  # also discovers filter values
$ ntsk aicc analytics alerts-matrix --start 30d
$ ntsk aicc analytics alert-policies --detection DLP
$ ntsk aicc data-protection summary anthropic  # anthropic|mscopilot|chatgpt
$ ntsk aicc data-protection violations anthropic --severity critical
        

Cloud Security

DSPM, SPM, RBI, ATP, IPS, and Threat Intelligence modules.

dspm — Data Security Posture Management

          $ ntsk dspm list-types                          # list valid resource types
$ ntsk dspm resources tables --limit 10       # positional RESOURCE_TYPE arg
$ ntsk dspm datastores connect DS_ID
$ ntsk dspm datastores scan DS_ID
$ ntsk dspm analytics classification              # metric types are API-dependent
        

Use ntsk dspm list-types to discover valid resource types. The resources subcommand takes a positional RESOURCE_TYPE argument. Analytics metric types are API-dependent and vary by tenant configuration.

spm — SaaS Security Posture

          $ ntsk spm apps list
$ ntsk spm apps get "Workday"
$ ntsk spm posture-score
$ ntsk spm rules list
$ ntsk spm changes
$ ntsk spm inventory
        

atp — Advanced Threat Protection

          # Scan a file for malware
$ ntsk atp scan-file -f suspicious.exe

# Scan a URL
$ ntsk atp scan-url --url "https://suspect.site"

# Get scan report
$ ntsk atp report JOB_ID
        

ips — Intrusion Prevention System

          $ ntsk ips status
$ ntsk ips allowlist list
$ ntsk ips allowlist add 10.0.0.0/8
$ ntsk ips signatures --search "CVE-2024"
        

intel — Threat Intelligence

          $ ntsk intel url-lookup --url "https://suspect.site"
$ ntsk intel url-recategorize --url "https://miscat.site"
$ ntsk intel false-positive --url "https://legit.site"
        

rbi — Remote Browser Isolation

          $ ntsk rbi apps list
$ ntsk rbi browsers
$ ntsk rbi categories
$ ntsk rbi templates list
        

Infrastructure

dns — DNS Security

          $ ntsk dns profiles list
$ ntsk dns profiles create "Corporate DNS"
$ ntsk dns profiles deploy
$ ntsk dns categories
$ ntsk dns groups list
$ ntsk dns record-types
$ ntsk dns tunnels
        

ipsec — IPsec VPN

          $ ntsk ipsec tunnels list
$ ntsk ipsec tunnels create --name "HQ-Tunnel" \
    --site-ip 203.0.113.1 --bandwidth 200
$ ntsk ipsec pops list --region EU
        

Bandwidth: 50, 100, 150, 200, 250, 1000 Mbps. Encryption: AES128-CBC, AES256-CBC, AES256-GCM.

enrollment — Device Enrollment

          $ ntsk enrollment tokens list
$ ntsk enrollment tokens create --name "Sales" --max-devices 100
$ ntsk enrollment tokens delete TOKEN_ID
        

rbac — Role-Based Access Control

          $ ntsk rbac roles list
$ ntsk rbac roles get ROLE_ID
$ ntsk rbac roles create --name "Auditor"
$ ntsk rbac admins list
        

Monitoring

dem — Digital Experience Management

Metrics queries, experience alerts, entities, states, traceroutes, field definitions, monitored apps, probes, alert rules, and per-user/device telemetry (CPU, memory, disk, network, RCA).

          # Query UX scores per user
$ ntsk dem metrics query -d ux_score \
    --select '["user_id", {"avg": ["avg", "score"]}]' \
    --groupby user_id --begin 1711929600000 --end 1712016000000

# Per-site ISP table: avg DNS, ISP latency to POP, POPs used, apps reached (last 24h)
$ ntsk dem sites summary
$ ntsk dem sites summary --where '["=", "country", ["$", "France"]]'   # DEM JSON syntax, sent to the API (not the global --where)

# Public 48h dataset endpoint (works with scoped API tokens; countDistinct/topK5, µs -> ms via "/")
$ ntsk dem dataset query -d http_steered \
    --select '["site_name", {"avg_dns_ms": ["/", ["avg", "dns_time"], 1000]}, {"pops_used": ["countDistinct", "pop_name"]}]' \
    --groupby site_name --begin 1725364316000 --end 1725450716000

# List users with poor experience scores
$ ntsk dem entities list --start-time 1710000000 --end-time 1710086400 \
    --exp-score "0~30"

# Search critical alerts
$ ntsk dem experience-alerts search --severity critical,high

# Get alert details and impacted entities
$ ntsk dem experience-alerts get ALERT_ID
$ ntsk dem experience-alerts entities ALERT_ID

# Query agent/client states
$ ntsk dem states query -d agent_status -s '["user_id", "status"]'

# Traceroute data
$ ntsk dem traceroute query -d traceroute_pop \
    --begin 1711929600000 --end 1712016000000

# Discover fields and list monitored apps
$ ntsk dem fields list
$ ntsk dem apps list

# Probe and alert rule management
$ ntsk dem probes list
$ ntsk dem network-probes list
$ ntsk dem alerts list

# --- ADEM User/Device Telemetry ---

# One-shot diagnostic report from ticket info
$ ntsk dem users diagnose -u alice@example.com \
    --start-time 1710000000 --end-time 1710086400
$ ntsk dem users diagnose -u alice@example.com \
    --start-time 1710000000 --end-time 1710086400 --include-npa

# List devices for a user (get device IDs)
$ ntsk dem users devices -u alice@example.com \
    --start-time 1710000000 --end-time 1710086400

# Detailed device info (hardware, OS, geo, IPs)
$ ntsk dem users device-details -u alice@example.com -d DEVICE-UUID \
    --start-time 1710000000 --end-time 1710086400

# Applications on a device (with per-app experience scores)
$ ntsk dem users applications -u alice@example.com -d DEVICE-UUID \
    --start-time 1710000000 --end-time 1710086400

# Root cause analysis — weighted root-cause tree + component scores
$ ntsk dem users rca -u alice@example.com -d DEVICE-UUID \
    --start-time 1710000000 --end-time 1710086400

# Aggregated scores (app, device, network, experience)
$ ntsk dem users scores -u alice@example.com -d DEVICE-UUID \
    --start-time 1710000000 --end-time 1710086400

# Network latency, packet loss & jitter timeseries
$ ntsk dem users network -u alice@example.com -d DEVICE-UUID \
    --start-time 1710000000 --end-time 1710086400

# NPA hosts and network path graph
$ ntsk dem users npa-hosts -u alice@example.com -d DEVICE-UUID \
    --start-time 1710000000 --end-time 1710086400
$ ntsk dem users npa-network-paths -u alice@example.com -d DEVICE-UUID \
    --npa-host 10.100.12.4 --start-time 1710000000 --end-time 1710086400

# User info, locations, experience score timeseries
$ ntsk dem users info -u alice@example.com \
    --start-time 1710000000 --end-time 1710086400
$ ntsk dem users exp-score -u alice@example.com -d DEVICE-UUID \
    --start-time 1710000000 --end-time 1710086400

# Traceroute — list timestamps, then fetch path
$ ntsk dem users traceroute-ts -u alice@example.com -d DEVICE-UUID \
    --start-time 1710000000 --end-time 1710086400
$ ntsk dem users traceroute -u alice@example.com -d DEVICE-UUID \
    --start-time 1710050000 --end-time 1710050000
        

notifications — Templates & Delivery

          $ ntsk notifications templates list
$ ntsk notifications templates get TPL_ID
$ ntsk notifications settings get
        

tokens — API Token Management

          $ ntsk tokens list
$ ntsk tokens create --name "ci-pipeline" \
    --endpoints "/api/v2/events,/api/v2/alerts"
$ ntsk tokens get TOKEN_ID
$ ntsk tokens revoke TOKEN_ID
        

status — Tenant Health Overview

Concurrent fetch of alerts, events, publishers, private apps, and SCIM users. Use --extended / -x to also fetch SCIM groups, URL lists, NPA policy rules, IPsec tunnels, RBAC roles, and IPS status.

          $ ntsk status
$ ntsk status --extended   # include config resource counts
$ ntsk status -x -o json   # extended as JSON
        

Utility Commands

doctor

Comprehensive setup diagnostic. Checks config file, profile, tenant, credentials, CA bundle, and API connectivity.

$ ntsk doctor

tenant

Show tenant configuration, auth method, and API connectivity status.

$ ntsk tenant

commands

Print the full command tree with argument signatures (e.g. resources <RESOURCE_TYPE>) for discoverability. Use --flat for a one-per-line list of executable commands, or --json for machine-readable output.

$ ntsk commands
$ ntsk commands --flat   # one command per line (best for scripting)
$ ntsk commands --flat --json   # flat JSON array
$ ntsk commands --json   # full JSON tree with args & options

docs

Documentation and help — open docs, search, view API reference, and JQL syntax.

          $ ntsk docs open          # open docs in browser
$ ntsk docs search "URL list"
$ ntsk docs jql            # JQL syntax reference
$ ntsk docs api            # API reference link
        

JQL Query Syntax

JSON Query Language for filtering events, alerts, and incidents. Run ntsk docs jql for the full reference.

Same syntax, client-side: `--where`

Every operator below also works locally on any command's output via the global --where option, with dotted paths into nested fields (host_info.os like "win*"). See Querying Results. On events, alerts and incidents keep using --query to fetch less, then --where to refine.

Operators

Operator	Meaning	Example
`eq`	Equals	`alert_type eq "DLP"`
`ne`	Not equals	`status ne "closed"`
`lt` / `gt`	Less / greater than	`cci gt 80`
`le` / `ge`	Less/greater or equal	`timestamp ge 1700000000`
`in`	In list	`app in ["Box","Dropbox"]`
`like`	Wildcard match	`user like "*@acme.com"`

Logical combinators

Combinator	Example
`AND`	`alert_type eq "DLP" AND severity eq "high"`
`OR`	`app eq "Box" OR app eq "Dropbox"`

Common filter fields

alert_type severity user app action access_method cci ccl domain srcip dstip category

# DLP alerts for a specific user in the last week
$ ntsk alerts list --query 'alert_type eq "DLP" AND user eq "alice@acme.com"' --since 7d

# High-risk cloud apps with low CCI
$ ntsk events application --query 'cci lt 50 AND action eq "block"' --start 24h

# Alerts for specific apps
$ ntsk alerts list --query 'app in ["ChatGPT","Google Bard"] AND alert_type eq "AI Security"'

# Wildcard user matching
$ ntsk events list -t page --query 'user like "*@engineering.acme.com"'

Error Handling & Exit Codes

Typed exceptions with actionable suggestions and distinct exit codes for scripting.

Exit Code	Exception	HTTP Status	Meaning	Suggestion
`1`	`APIError`	5xx, timeout	Generic API error	Check connectivity, retry
`1`	`RateLimitError`	429	Rate limit exceeded	Raised only after 3 automatic retries; wait, then narrow the query
`2`	`ValidationError`	400	Invalid input	Check JQL syntax: `ntsk docs jql`
`3`	`AuthError`	401	Authentication failed	Check token validity or re-login
`4`	`AuthorizationError`	403	Permission denied	Verify account permissions / RBAC role. Error now includes license/scope hints when available.
`5`	`NotFoundError`	404	Resource not found	Context-specific: license check, ID validation
`6`	`SSLError`	—	SSL/TLS verification failed	Set `NETSKOPE_CA_BUNDLE` or `ntsk config set-ca-bundle`
`78`	`ConfigError`	—	Missing/invalid configuration	Run `ntsk config setup`
`130`	—	—	Keyboard interrupt (Ctrl+C)	—

SSL/TLS troubleshooting

If your organization uses Netskope client for SSL inspection, the CLI needs the Netskope CA certificate. The CLI auto-detects common paths:

Platform	Auto-detected path
macOS	`/Library/Application Support/Netskope/STAgent/data/nscacert*.pem`
Linux	`/opt/netskope/stagent/nsca/nscacert*.pem`
Windows	`C:\ProgramData\Netskope\STAgent\data\nscacert*.pem`

      # Manual CA bundle configuration
$ export NETSKOPE_CA_BUNDLE="/path/to/ca-bundle.pem"
# Or persist in profile
$ ntsk config set-ca-bundle "/path/to/ca-bundle.pem"
    

# Use exit codes in scripts
$ ntsk alerts list --since 1h --count -q
$ echo $?  # 0 = success, non-zero = error

# Example: alert on failure
if ! ntsk alerts list --count -q > /dev/null 2>&1; then
    echo "CLI failed with exit code $?"
fi

Troubleshooting

User field shows “redacted” in alerts & events

When running commands like ntsk alerts list or ntsk events list, the user field may appear as “redacted”. This is not a CLI issue — the Netskope API itself returns the redacted value. It is caused by a tenant-level anonymization / de-identification policy configured in the Netskope admin console.

You can confirm this by inspecting the raw API response:

      $ ntsk alerts list --since 24h --limit 1 -o json --raw
# If the "user" field is "redacted" in the raw JSON, the API is redacting it server-side
    

How to resolve

Disable or adjust anonymization — In the Netskope admin console, go to Settings → Security Cloud Platform → Data Protection → Anonymization and disable or modify the anonymization policy for the relevant data types.
Check API token privileges — Some tenants require a dedicated de-anonymization scope on the API token. Verify your token has the necessary privileges to view unredacted PII.
Use a reporting token — Certain tenants issue separate “reporting” API tokens with full visibility. Ask your Netskope administrator if a different token type is available.

Workflows & Recipes

Common real-world patterns combining multiple commands.

Security

Daily Security Dashboard

Morning security review — summarize alerts, check critical incidents, review publisher health.

#!/bin/bash - Daily security dashboard

# Alert summary by type
echo "=== Alert Summary (last 24h) ==="
ntsk alerts summary --by alert_type --since 24h

# Critical DLP alerts
echo "=== DLP Alerts ==="
ntsk alerts list --query 'alert_type eq "DLP"' --since 24h --limit 20

# Publisher health
echo "=== Publishers ==="
ntsk publishers list

# Compromised credentials
echo "=== Compromised Credentials ==="
ntsk alerts list -t "Compromised Credential" --since 24h

Inventory

Fleet Inventory from `devices list`

Discover the device schema, then build a CSV of stale Windows endpoints — entirely with the global query options, no jq needed.

# 1. What fields are there? (works on the v1 fallback schema too)
ntsk devices list --limit 50 --list-fields

# 2. Windows devices with EPDLP errors, newest first, four columns, as CSV
ntsk devices list --limit 500 \
  --where 'host_info.os like "win*" and epdlp.criticalErrorsCount gt 0' \
  --sort last_event_timestamp:desc \
  --fields hostname,host_info.os_version,epdlp.criticalErrorsCount,last_event_timestamp \
  -o csv > windows-epdlp-errors.csv

# 3. How many devices have never reported an IdP?
ntsk devices list --limit 500 --where 'idps eq null' --count

Data

Export & Analyze with jq

Pipe JSON output to jq for custom analysis and transformation.

# Top 10 users by alert count
$ ntsk -o json alerts list --since 7d --limit 1000 | \
  jq '[.[].user] | group_by(.) | map({user: .[0], count: length}) | sort_by(-.count) | .[:10]'

# Export DLP incidents to CSV for compliance report
$ ntsk -o csv alerts list --query 'alert_type eq "DLP"' --since 30d \
  -f alert_name,user,app,timestamp,dlp_profile,dlp_rule_severity > dlp_report.csv

# Unique applications seen in the last week
$ ntsk -o json events application --start 7d --limit 5000 | \
  jq '[.[].app] | unique | sort'

# Count events by category using JSONL for streaming
$ ntsk -o jsonl events page --start 24h --limit 5000 | \
  jq -s 'group_by(.category) | map({category: .[0].category, count: length}) | sort_by(-.count)'

CI/CD

CI/CD Pipeline Integration

Automate policy updates and security checks in your deployment pipeline.

# GitHub Actions example
env:
  NETSKOPE_TENANT: ${{ secrets.NETSKOPE_TENANT }}
  NETSKOPE_API_TOKEN: ${{ secrets.NETSKOPE_API_TOKEN }}

steps:
  - run: pip install netskope

  # Verify connectivity
  - run: ntsk doctor -q

  # Update URL blocklist from file
  - run: |
      ntsk policy url-list update 42 \
        --urls "$(cat blocklist.txt | tr '\n' ',')"
      ntsk policy deploy

  # Check for critical alerts (fail pipeline if found)
  - run: |
      COUNT=$(ntsk alerts list --query 'severity eq "critical"' --since 1h --count -q)
      if [ "$COUNT" -gt 0 ]; then
        echo "::error::$COUNT critical alerts in last hour"
        exit 1
      fi

Multi-tenant

Multi-Tenant Management

Use profiles to switch between tenants seamlessly.

# Set up multiple profiles
$ ntsk config create-profile dev
$ ntsk config set-tenant dev.goskope.com --profile dev
$ ntsk config set-token --profile dev

$ ntsk config create-profile prod
$ ntsk config set-tenant prod.goskope.com --profile prod
$ ntsk config set-token --profile prod

# Query different tenants
$ ntsk --profile dev alerts summary --by alert_type
$ ntsk --profile prod alerts summary --by alert_type

# Or set via env var for scripts
$ NETSKOPE_PROFILE=prod ntsk publishers list

Investigation

User Investigation Workflow

# 1. Check user confidence index (risk score)
$ ntsk incidents uci suspect@company.com --from-time 30d

# 2. Get their alerts
$ ntsk alerts get --user suspect@company.com --since 30d

# 3. Check UBA anomalies
$ ntsk incidents anomalies --users suspect@company.com

# 4. Review their application usage
$ ntsk events get --type application --user suspect@company.com --since 30d

# 5. Check for data exfiltration (DLP alerts)
$ ntsk alerts get --user suspect@company.com --type DLP --since 30d

Environment Variables

All settings can be overridden via environment variables. They take precedence over config file values but are overridden by CLI flags.

Variable	Description	Example
`NETSKOPE_TENANT`	Tenant hostname (overrides profile config)	`sedemo.goskope.com`
`NETSKOPE_API_TOKEN`	API v2 token (overrides keyring and config)	`your-api-token`
`NETSKOPE_PROFILE`	Active configuration profile	`production`
`NETSKOPE_CA_BUNDLE`	Custom CA certificate bundle path for SSL inspection	`/etc/ssl/netskope-ca.pem`
`NETSKOPE_WIDE`	Set to `1` to show all table columns	`1`
`NETSKOPE_OUTPUT_FORMAT`	Default output format	`json`
`NO_COLOR`	Disable colored output when set to any value	`1`
`REQUESTS_CA_BUNDLE`	Standard Python CA bundle (also checked)	`/etc/ssl/certs/ca-certificates.crt`
`SSL_CERT_FILE`	Standard SSL certificate file (also checked)	`/etc/ssl/cert.pem`

Shell Completion

Tab-completion for commands, subcommands, and options.

One-step install

        # Auto-detects your shell
$ ntsk completion install bash
$ ntsk completion install zsh
$ ntsk completion install fish
$ ntsk completion install powershell
      

Manual setup

        # Print script to stdout
$ ntsk completion show zsh > ~/.zfunc/_netskope

# Bash
$ ntsk completion show bash >> ~/.bashrc

# Fish
$ ntsk completion show fish > \
  ~/.config/fish/completions/ntsk.fish
      

Full Command Tree

Every command and subcommand. Output of ntsk commands.

Show full command tree (290+ commands)

        netskope
├── aicc
│   ├── guide           Data model, command map, workflow recipes
│   ├── overview        Entity counts + traffic/session/alert KPIs
│   ├── coverage        Earliest date with AICC data
│   ├── report          AI Risk Report data bundle (json / markdown)
│   ├── apps ─ list / get / status / identities / deployments / trend / violations
│   ├── mcp ─ list / get / identities / deployments / trend / violations
│   ├── models ─ list / get / identities / deployments / trend
│   ├── agents ─ list / get / identities / deployments / trend
│   ├── identities ─ list / get / trend / models / agents / mcp
│   ├── extensions ─ get / deployments / identities
│   ├── analytics ─ entities / counts / sums / breakdown / alerts-matrix / alert-policies
│   └── data-protection ─ summary / violations
├── alerts
│   ├── get         Look up alerts by ID, user, app, or other fields
│   ├── list        List security alerts
│   ├── summary     Summarise alerts by grouping field
│   └── types       List known alert types
├── atp
│   ├── report      Retrieve scan report
│   ├── scan-file   Submit file for malware scan
│   ├── scan-url    Submit URL for threat scan
│   └── submission  Retrieve TPaaS submission report
├── auth
│   ├── login       Browser-based SSO login
│   ├── logout      Clear stored credentials
│   ├── status      Show auth status
│   └── token       Display masked token info
├── commands          Print full command tree
├── completion
│   ├── install     Install shell completion
│   └── show        Print completion script
├── config
│   ├── create-profile  Create new profile
│   ├── profiles        List all profiles
│   ├── set-ca-bundle   Set custom CA bundle
│   ├── set-tenant      Set tenant hostname
│   ├── set-token       Store API token securely
│   ├── setup           Interactive setup wizard
│   ├── show            Display effective config
│   ├── test            Test API connectivity
│   └── use-profile     Switch active profile
├── dem
│   ├── alerts ─ list / create          (alert rules)
│   ├── apps ─ list                     (monitored apps)
│   ├── entities ─ list                 (users & scores)
│   ├── experience-alerts ─ search / get / entities
│   ├── fields ─ list                   (field definitions)
│   ├── metrics ─ query                 (17 data sources)
│   ├── network-probes ─ list
│   ├── probes ─ list / create
│   ├── states ─ query                  (agent/client)
│   ├── traceroute ─ query              (network paths)
│   └── users                              (ADEM telemetry)
│       ├── diagnose                           (composite diagnostic)
│       ├── devices / device-details / info / locations
│       ├── applications / scores / exp-score / rca
│       ├── network / npa-hosts / npa-network-paths
│       └── traceroute / traceroute-ts
├── devices
│   ├── list            List managed devices
│   ├── supported-os    Supported OS versions
│   └── tags ─ list / create / get / update / delete
├── dns
│   ├── categories      Domain categories
│   ├── groups ─ list / create / get / update / delete / deploy
│   ├── profiles ─ list / create / get / update / delete / deploy
│   ├── record-types    DNS record types
│   └── tunnels         DNS tunnels
├── docs
│   ├── api / jql / open / search
├── doctor                Setup diagnostic
├── dspm
│   ├── analytics       DSPM analytics
│   ├── datastores ─ connect / scan
│   ├── list-types      List valid resource types
│   └── resources <RESOURCE_TYPE>  List DSPM resources
├── enrollment
│   └── tokens ─ list / create / delete
├── events
│   ├── get         Look up events by ID, user, app, or other fields
│   ├── list / alert / application / audit
│   ├── client-status / epdlp / incident
│   └── infrastructure / network / page / transaction
├── incidents
│   ├── anomalies / forensics / list / search / uci / update
│   └── notes
│       └── list / add / delete
├── intel
│   ├── false-positive / url-lookup / url-recategorize
├── ips
│   ├── allowlist ─ add / list
│   ├── signatures    IPS signatures
│   └── status        IPS feature status
├── ipsec
│   ├── pops ─ list
│   └── tunnels ─ list / create / get / update / delete
├── notifications
│   ├── settings ─ get
│   └── templates ─ list / create / get / update / delete
├── npa
│   ├── alerts-config ─ get / update
│   ├── app-publishers ─ add / remove / replace
│   ├── apps ─ list / get / create / update / delete / bulk-delete / policy-check
│   ├── discovery ─ get / update
│   ├── policy ─ rules (CRUD) / groups (CRUD)
│   ├── publishers ─ list / get / create / delete / update / upgrade
│   │   ├── local-brokers ─ list / get / create / delete / update / config
│   │   └── upgrade-profiles ─ list / get / create / delete / update / assign
│   ├── search / validate-name
│   └── tags ─ list / get / create / update / delete / add / remove / replace
├── policy
│   ├── deploy          Deploy pending changes
│   └── url-list ─ list / create / get / update / delete
├── publishers
│   ├── list / get / create / update / delete
│   ├── local-brokers ─ list
│   └── upgrade-profiles ─ list
├── rbac
│   ├── admins ─ list
│   └── roles ─ list / get / create / update / delete
├── rbi
│   ├── apps ─ list
│   ├── browsers / categories
│   └── templates ─ list / get
├── services
│   ├── cci             CCI lookup
│   ├── private-apps ─ list / get / create
│   ├── publishers ─ list / get
│   └── tags ─ list / get / create / update / delete
├── spm
│   ├── apps ─ list / get
│   ├── changes / inventory / posture-score
│   └── rules ─ list
├── status                Tenant health overview
├── steering
│   ├── config ─ get / update
│   └── private-apps ─ list / get
├── tenant                Show tenant info
├── tokens
│   ├── list / create / get / update / revoke
└── users
    ├── list / get / create / update / delete
    └── groups ─ list / get / members / create / update / delete
      

The complete guide to Netskope CLI

Installation

pipx (isolated install)

pip (all platforms)

uv (isolated install)

Homebrew (macOS / Linux)

From source

Verify installation

Getting Started

Configure your tenant

Authenticate

Start using the CLI

AI Agent Skill

Architecture

Request Flow

Configuration Resolution

Core Modules

Command Pattern

Configuration

Config file layout

XDG directories

Profile management commands

Credential storage priority

Authentication

Auth Flow

API Token Auth

Browser SSO Auth

Output Formats

Auto-unwrapping

Timestamp conversion

TTY detection

Global Flags

Flag position flexibility

Querying Results: Discover, Select, Filter, Sort

Discover — --list-fields

Select — --fields / -f

Filter — --where

Sort — --sort, and combine

Client-side vs server-side

Command Reference

alerts

events

Event Types

Two equivalent approaches

incidents

users

policy

publishers

services

npa

Subcommand tree

steering

devices

aicc

Orientation — start here

AI Risk Report — AIRR data in one command

Inventories — apps, mcp, models, agents

Drill-down — per-entity detail

Identities — users & blind spots

Analytics & DLP — KPIs, charts, alert posture

Cloud Security

dspm — Data Security Posture Management

spm — SaaS Security Posture

atp — Advanced Threat Protection

ips — Intrusion Prevention System

intel — Threat Intelligence

rbi — Remote Browser Isolation

Infrastructure

dns — DNS Security

ipsec — IPsec VPN

enrollment — Device Enrollment

rbac — Role-Based Access Control

Monitoring

dem — Digital Experience Management

notifications — Templates & Delivery

tokens — API Token Management

status — Tenant Health Overview

Utility Commands

doctor

tenant

Discover — `--list-fields`

Select — `--fields` / `-f`

Filter — `--where`

Sort — `--sort`, and combine

Same syntax, client-side: `--where`

Fleet Inventory from `devices list`