Guide

Get started

CEPL runs in Ceplin: in its terminal program, ceplin, and in its web workspace. This page covers running ceplin once it is downloaded, setting API keys, running your first lines, and using the prompt.

#Run ceplin after downloading it

ceplin is one file, with nothing to install and nothing else it needs. There is one for each system, on the download page with its checksum:

ceplin is free to use under the Ceplin Terminal Beta Licence.

On Linux or macOS, open a terminal in the folder you downloaded it to. Rename it ceplin, make it executable, and run it:

cd ~/Downloads
mv ceplin-linux-amd64 ceplin       # the name of the file you downloaded
chmod +x ceplin
./ceplin -version
./ceplin -offline

-version prints the version. -offline starts the prompt on Ceplin's sample data, with no keys and no network, so you can try every example on this site straight away. /exit or Ctrl+D leaves it.

On a Mac, a downloaded file is quarantined, and macOS refuses to open it ("cannot be opened because the developer cannot be verified"). Clear it once, after renaming it:

xattr -d com.apple.quarantine ceplin

On Windows, open PowerShell or Windows Terminal (Windows 10 or later) in the download folder, rename it, and run it:

cd $HOME\Downloads
Rename-Item ceplin-windows-amd64.exe ceplin.exe     # or ceplin-windows-arm64.exe
.\ceplin.exe -version
.\ceplin.exe -offline

If Windows blocks a file downloaded from the internet, Unblock-File .\ceplin.exe clears the mark it was given.

Keep the name ceplin or ceplin.exe, or any name that starts with ceplin-. The file chooses what it runs from its own name: under another name it starts Ceplin's web workspace instead of the terminal program.

To run it from any folder, put it on your PATH:

sudo mkdir -p /usr/local/bin
sudo install -m 0755 ceplin /usr/local/bin/ceplin
ceplin -offline

On Windows, move ceplin.exe to a folder of your own, such as $HOME\bin, and add that folder to PATH in Settings, under System, About, Advanced system settings, Environment Variables. ceplin reads and writes files in the folder it is started in, so start it where your files are (see Files and state).

#Set your API keys

Most verbs need no key. Three providers do, and a fourth takes one if you have it. ceplin reads them from environment variables:

urlscan.io, DNS, RDAP, routing and certificate lookups need no key, and OTX answers without one. Without its key, an AbuseIPDB or MalwareBazaar verb answers from Ceplin's sample data and geo() is refused; the prompt says so when it starts.

export ABUSEIPDB_API_KEY=your-key
export IP2LOCATION_API_KEY=your-key
export MALWAREBAZAAR_API_KEY=your-key
./ceplin

On Windows, use $env:ABUSEIPDB_API_KEY = "your-key" for the current session, or setx ABUSEIPDB_API_KEY "your-key" to keep it. In ceplin, /keys shows which keys are set.

#Your first lines

Paste an artefact on its own and Ceplin tells you what type it is:

>>> 185.215.113.66
[OK] Recognised ip
    185.215.113.66

Put it in quotes and add a verb to look it up. Add [field] to keep one field of the result:

>>> "185.215.113.66".abuseipdb()
[OK] IP reputation on 185.215.113.66 via AbuseIPDB
    score:         ● 100
    total_reports: ● 1148
    isp:           Prospero OOO
    usage_type:    Data Center/Web Hosting/Transit
    country:       Russian Federation
    is_tor:        ● false
    last_reported: 2026-08-12T22:41:07+00:00

>>> "185.215.113.66".abuseipdb()[score]
[OK] IP reputation [score] on 185.215.113.66 via AbuseIPDB
    100

A field can be passed on to the next verb. This line resolves a domain, then looks up the reputation of the address it resolves to:

>>> "cdn-telemetry.xyz".resolve()[ip].abuseipdb()[score, isp]
[OK] IP reputation [score, isp] on 45.9.148.112 via AbuseIPDB
    score: ● 100
    isp:   IP Volume inc

#Reading a result

Every result starts with a marker, then what ran, on which value, and through which provider.

Documentation and private addresses are never sent to a provider, so a lookup on one is skipped and costs nothing:

>>> "203.0.113.42".abuseipdb()
[--] IP reputation on 203.0.113.42 via AbuseIPDB
    reserved/documentation range (203.0.113.0/24); no public reputation exists; not looked up, no API call made

#Using the prompt

• Tab lists what can follow the text before the cursor: verbs after a dot (with their provider), fields after [, your saved verbs after .@, commands after /, and checks inside { }. Use the arrow keys to move and Tab or Enter to choose.
• The line is coloured as you type: the artefact in blue, [fields] in green, { } by depth, and // comments in grey.
• Enter inside { } starts a new line, so a block can be written over several lines. Alt+Enter or Ctrl+J starts a new line anywhere.
• Up and down move between the lines of a block, then through history. History is kept between runs.
• Ctrl+C cancels a running line and keeps what had already answered.
• /help lists the commands and keys. /help ip lists the verbs that take an IP address, and /help abuseipdb shows one verb in full.

While a line runs, a line under the prompt shows the lookup in progress and how many of the planned calls have answered.

#Scripts and one-off lines

ceplin runs a line given after it, a file of lines, or lines from a pipe, one statement per line, and prints plain text:

ceplin '"185.215.113.66".abuseipdb()[score]'
ceplin hunt.cepl
ceplin < hunt.cepl

Put a line in single quotes so the shell keeps its double quotes. When the shell takes them off anyway, as ceplin "185.215.113.66".abuseipdb() in bash or zsh and Windows PowerShell 5.1 do, ceplin puts them back on the artefact. In cmd.exe, write the inner quotes as \".

A script line that would make more API calls than the limit runs only with -yes. ceplin -h lists the flags.

#Files and state

ceplin reads and writes files in the folder it was started in. "proxy.csv".import() reads proxy.csv from that folder, and relative paths, absolute paths and ~/ work too. .export() writes there, or to a path you give it: .export("out/report.xlsx"). See Files.

Saved verbs, history and the audit trail are kept in ~/.local/state/ceplin on Linux ($XDG_STATE_HOME/ceplin when that is set), ~/Library/Application Support/ceplin on macOS and %AppData%\ceplin on Windows. Set CPLN_STATE_DIR to keep them somewhere else.

#Next steps

The language tour covers the whole language with examples. The cookbook has complete investigations you can adapt.