Interactive Session

Once the tool starts with sudo bettercap, you’ll see an interactive session (Metasploit-style). Here you can run commands, enable or disable modules, and get or set parameters. See command line arguments for all options.

Tip

Each command can either be executed singularly, or concatenated by the ; operator, for instance, instead of typing:

clear
net.show

You can simply type: clear; net.show

Functionalities are organized into:

• Core commands: Basic operations like setting parameters, getting values, and clearing the screen
• Session modules: Feature-specific sub commands that use session parameters for configuration

Caplets

You can also script your interactive session using caplets. Caplets are script files with a .cap extension. Think of them like Metasploit’s .rc files. Each line is a command that executes at runtime.

For instance, a simple caplet that sets the ticker.commands parameter and enables the net.probe and ticker modules would be:

example.cap

set ticker.commands 'clear; net.show; events.show 10'
net.probe on
ticker on

Once saved as an example.cap file, you’ll be able to load and execute it via:

sudo bettercap -caplet /path/to/example.cap

It is also possible to load a caplet by name, without its path and extension:

sudo bettercap -caplet example

In this case the search order will be:

1. ./example.cap
2. ./caplets/example.cap
3. Any folder in the environment variable $CAPSPATH (values are separated by :, like for $PATH).
4. /usr/local/share/bettercap/caplets/example.cap (the default path where caplets are installed).

You can install or update the predefined caplets from the caplets repository. Use the caplet module from the command line:

sudo bettercap -eval "caplets.update; q"

Or simply from the interactive session:

caplets.update

You can then check what’s been installed in /usr/local/share/bettercap/caplets/ with the command:

caplets.show

Command Line Arguments

The basic command line arguments ( bettercap -h ) are:

-autostart MODULES

A comma separated list of modules that are automatically started (default to events.stream).

-caplet FILENAME

Read commands from this file and execute them in the interactive session.

-caplets-path PATH

Specify an alternative base path for caplets.

-eval COMMANDS

Run one or more commands separated by ; in the interactive session, used to set variables via command line.

-script FILENAME

Load a session script.

-iface INTERFACE

Network interface to bind to. If empty, the default interface is auto-selected. Accepts interface name, IP, or MAC address.

-gateway-override ADDRESS

Use the provided IP address instead of the default gateway. If not specified or invalid, the default gateway is auto-detected.

-no-history

Disable the interactive session history file ~/.bettercap.history.

-no-colors

Disable terminal colors and effects.

-env-file FILENAME

Preload parameter values from this file if found. Set to empty to disable environment persistence. Default: ~/bettercap.env.

-silent

Suppress all logs which are not errors.

-cpu-profile FILENAME

Write a CPU profile file when exiting (used for debugging and benchmarking).

-mem-profile FILENAME

Write memory profile file when exiting (used for debugging and benchmarking).

-debug

Enable debug messages (must be used to report bugs).

-version

Print version and build information, then exit (must be used to report bugs).

Core Commands

help

Will list all available commands and print the name of each module and its status (running or not running).

help MODULE_NAME

Will print the module specific help menu, with its sub commands and parameters.

active

Show which modules are running and their parameters.

quit or q

Close the session and exit.

sleep SECONDS

Sleep for the given amount of seconds.

get PARAMETER

Get the value of the specified parameter, use * for all.

set PARAMETER VALUE

Set the value of PARAMETER to VALUE, use "" or '' to clear its contents.

read PARAMETER PROMPT

Show a PROMPT to ask the user for input that will be saved inside PARAMETER.

clear

Clear the screen.

include CAPLET

Load and run this caplet in the current session. You can also just specify the caplet name as a command.

!COMMAND

Execute a shell command and print its output into the session.

alias MAC NAME

Assign an alias to a given endpoint given its MAC address (will be persistent on ~/bettercap.aliases).

Tip

Aliases are persisted on disk and shared across modules and sessions. An alias set on one network will appear in WiFi modules when resolving wireless stations. You’ll see who’s connecting to what.

Customizing the Prompt

The interactive session prompt can be modified by setting the $ variable. For instance:

set $ something

This sets the prompt to the string something.

You can also access parameters and use colors/effects with special operators. See the $ parameter default value:

get $

{by}{fw}{cidr} {fb}{env.iface.ipv4} {reset} {bold}» {reset}

The available effects are:

Operator	Description
{bold}	Set text to bold.
{dim}	Set dim effect on text.
{r}	Set text foreground color to red.
{g}	Set text foreground color to green.
{b}	Set text foreground color to blue.
{y}	Set text foreground color to yellow.
{fb}	Set text foreground color to black.
{fw}	Set text foreground color to white.
{bdg}	Set text background color to dark gray.
{br}	Set text background color to red.
{bg}	Set text background color to green.
{by}	Set text background color to yellow.
{blb}	Set text background color to light blue.
{reset}	Reset text effects (added by default at the end of the prompt if not specified).

There are also other operators you can use in order to access specific information about the session.

Operator	Description
{cidr}	Selected interface subnet CIDR.
{net.sent}	Number of bytes being sent by the tool on the network.
{net.sent.human}	Number of bytes being sent by the tool on the network (human readable form).
{net.errors}	Number of errors while sending packets.
{net.received}	Number of bytes being sniffed from the tool on the network.
{net.received.human}	Number of bytes being sniffed from the tool from the network (human readable form).
{net.packets}	Number of packets being sniffed by the tool from the network.

You can also access any session variable using the {env.NAME-OF-THE-VAR} operator.

For example, the default prompt uses {env.iface.ipv4}. This is replaced by the iface.ipv4 session variable contents. Check it with get iface.ipv4.

Examples

Set the arp.spoof.targets parameter and enable the arp.spoof module:

sudo bettercap -eval "set arp.spoof.targets 192.168.1.20; arp.spoof on"

To quickly get a module’s help menu and quit (like a man command), use -eval:

sudo bettercap -eval "help net.recon; q"

Ask the user to fill the arp.spoof.targets parameter:

read arp.spoof.targets "Select the target to spoof: "

Set the alias “MY IPAD” to the device with MAC address DE:AD:DE:AD:BE:EF:

alias DE:AD:DE:AD:BE:EF MY IPAD