Platform CLI Tool

The cencli command line tool enables you to run search queries, look up assets, perform aggregations, and more—bringing the Censys Platform directly to your terminal window.

cencli is available to all registered Platform users with access to the API. Users on the Starter and Enterprise tiers have access to more functionality and data than Free users.

The cencli GitHub repo always contains the most up-to-date information about how to install and use the tool. This document contains general instructions for setup and basic use.

Prerequisites

• A Platform Personal Access Token (PAT).
• Optional: your organization ID to perform additional commands and retrieve entitled data.

Censys Credit consumption

cencli uses the credit consumption model that is utilized for Platform APIs.

Installation

Versioned releases of cencli for different platforms and architectures are available for download from the releases page on GitHub.

📘

Note

If you have the CLI tool for Censys Legacy Search installed on your system, you may need to uninstall it in order to easily use cencli. Both tools use similar command syntax.

An example setup process for an Apple MacBook pro with an Apple chip is:

1. Download the most recent arm_64 darwin binary available on the releases page. Extract the compressed file to a directory of your choice.
2. Add it to your path. Open Terminal on your Mac and run echo $SHELL to determine whether you are using zsh or bash.
   1. If you are using zsh:

      1. Open ~/.zshrc using a text editor like nano.

         nano ~/.zshrc

      2. Add the following line to the end of your file, replacing the path with the directory that the binary is in on your system.

         export PATH="$PATH:/path/to/your/directory"

      3. Save and apply the changes.

   2. If you are using bash:

      1. Open ~/.bash_profile using a text editor like nano.

         nano ~/.bash_profile

      2. Add the following line to the end of your file, replacing the path with the directory that the binary is in on your system.

         export PATH="$PATH:/path/to/your/directory"

      3. Save and apply the changes.

3. Close and reopen your terminal window.
   1. Depending on your security settings, you may need to explicitly allow the cencli binary to run on your system. To do this, go to System Settings > Privacy & Security > Security. If you already tried to run a cencli command, an alert for the tool will be present. Click Open Anyway to permit the tool to run the next time you use it.

Configuration

1. Run censys config auth add. Enter your PAT and a name to identify the token.
2. (Optional) Run censys config org-id add. Enter your organization ID and a name to identify it.

Data commands

cencli features the following commands to interact with Censys data:

• view
• search
• aggregate
• history
• censeye

You can run the -h or --help flag with any of these commands to see descriptions of them and the flags you can use with them.

view

The view command fetches information about a particular host, certificate, or web property asset at a particular point in time. Hosts are identified by an IP address, certificates by a SHA-256 hash, and web properties by a hostname and port combination joined by a colon.

Structure

censys view <asset> <flags>

Examples

View the record for 8.8.8.8:

censys view 8.8.8.8

View the record for platform.censys.io:80:

censys view platform.censys.io:80

You can retrieve information for multiple assets in a single command by separating assets with a comma. View the records for 1.1.1.1 and 2.2.2.2:

censys view 1.1.1.1,2.2.2.2

view flags

censys view 8.8.8.8 -a 2025-10-05T14:30:00Z

censys view -i hosts.txt

censys view 8.8.8.8 -s

search

The search command runs a search query across Platform datasets. Queries must be written in the Censys Query Language (CenQL) and wrapped in single or double quotes.

Structure

censys search <query> <flags>

Examples

Search for hosts in Russia running SSH on a nonstandard port:

censys search 'host.services:(protocol=SSH and not port=22) and host.location.country=Russia'

search flags

censys search --collection-id your-id-here "host.services.protocol=SSH"

censys search 'host.services:(protocol=SSH and not port=22) and host.location.country=Russia' -f 'host.ip'

censys search --max-pages 5 "host.services.port: 443 and host.location.country: Germany"

censys search 'cert.names=censys.com' -n 5

censys search 'web.endpoints: (path= {"/config", "/logs", "/uploads", "/backups"} and http.status_code: 200)' -s

aggregate

aggregate performs an aggregation on data in the Platform datasets. It has the same functionality as the Report Builder in the web UI.

Structure

censys aggregate <query> <field> <flags>

Examples

Break down the non-root paths present on web properties:

censys aggregate 'web.endpoints.path: * and NOT web.endpoints.path= "/"' web.endpoints.path

aggregate flags

censys aggregate -c your-collection-id "host.services.protocol=SSH" "host.services.port"

censys aggregate "host.services.protocol=SSH" "host.services.port" -l "host.services"

censys aggregate 'host.services.protocol=SSH' 'host.services.port' -f

censys aggregate 'host.services.protocol=SSH' 'host.services.port' -f -i

censys aggregate 'host.services.protocol=SSH' 'host.services.port' -f -i -n 10

censys aggregate 'host.services.protocol=SSH' 'host.services.port' -f -r

history

The history command retrieves historical data for hosts, web properties, and certificates, showing how assets have changed over time.

If you do not provide a duration or time frame, then the previous seven days of history will be retrieved.

To retrieve certificate history data, you must have access to the Threat Hunting module.

Structure

censys history <asset> <flags>

Examples

Retrieve the previous seven days of history for the host 186.169.70.5:

censys history 186.169.70.05

Retrieve the previous seven days of history for the certificate 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf:

censys history 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf

history flags

censys history 8.8.8.8 --start 2025-10-01T00:00:00Z

censys history 8.8.8.8 --end 2025-10-01T00:00:00Z

censys history 8.8.8.8 --start 2025-01-01T00:00:00Z --duration 30d

--duration flag

Supported units for the --duration flag are:

• h - hours
• d - days
• w - weeks (7 days)
• y - years (365 days)

Note the following interactions between --duration and other flags:

• If only --duration is specified, the time window is for the preceding seven days.
• If --start is specified, the window is from start to start+duration.
• If --end is specified, the window is from end-duration to end.
• If both --start and --end are specified, duration is ignored.

censeye

The censeye command helps identifies assets on the internet that share specific characteristics with a host you are investigating. It automatically extracts field-value pairs from a host and shows how many other assets share those same values, enabling you to pivot into related infrastructure and build threat hunting queries.

The output includes clickable queries that you can open in the Censys Platform web UI.

The censeye command is only available to organizations with access to the Threat Hunting module. Learn more about CensEye in the Threat Hunting module documentation.

Structure

censys censeye <asset> [flags]

censeye output

By default, censeye displays results in a formatted table with two columns:

• Count: The number of internet-facing assets that match this query
• Query: A clickable generated query (marked with * if interesting)

Queries marked with * are considered "interesting" because their counts fall within your configured rarity bounds.

You can also view results in an interactive table use the raw JSON output.

Examples

Find shared field-value pairs for the host 117.72.181.104:

censys censeye 117.72.181.104

censeye flags

censys censeye 8.8.8.8 -m 5

censys censeye 8.8.8.8 -M 200

censys censeye 8.8.8.8 -I

censys censeye 8.8.8.8 --raw

censys censeye 8.8.8.8 --raw --include-url

Additional flags

The following flags can be used with a number of different commands. Reference the documentation in GitHub for a complete list.