CLI Reference

setup

Interactive setup wizard. Guides you through license, CA certificate trust, DNS redirect info, and protection mode. Auto-triggered on first start or up.

# Interactive setup (run as root for CA trust + DNS)
sudo bleep setup

# Non-interactive with all defaults (for CI/Docker)
bleep setup --defaults

# Enterprise variant
sudo bleep-enterprise setup

Steps: License/Enrollment → CA Trust + System Env Vars → App Selection → Mode → Systemd Service. Re-run anytime to reconfigure. Skipped in non-TTY environments (pipes, cron).

start

Start the DNS redirect service. Sets system DNS to 127.0.0.1, intercepts AI traffic via DNS spoofing, and applies detection policies. Does not configure any applications — use up for auto-configuration.

bleep start
bleep start --mode warning
bleep start --log-file /var/log/bleep.log

The daemon runs in the foreground by default. Use a systemd service or & to background it.

up

Start the DNS redirect service and auto-configure common applications to trust the Bleep CA certificate. This is the recommended way to start Bleep on developer machines.

bleep up
bleep up --mode warning
BLEEP_LICENSE_KEY=LIC-XXXX bleep up

Alias for start. Configures CA trust for git, npm, and other tools automatically on startup. Since Bleep uses DNS redirect, all applications are protected automatically without any per-app proxy configuration.

down

Stop the DNS redirect service. CA trust configuration persists across restarts.

bleep down

status

Show protection status including running state, license info, CA certificate trust status, violation counts, and configured applications.

bleep status
bleep status --json

Use --json for machine-readable output. See the Status Output section for a full example.

policy list

List all detection policies with their ID, name, action, severity, and enabled state.

bleep policy list
bleep policy list --json

policy add

Add a new detection policy. Policies determine what action to take when a pattern is detected.

bleep policy add --name "Block AWS keys" --action block --severity critical
bleep policy add --name "Warn on emails" --action warn --severity medium --tags pii
bleep policy add --name "Redact SSNs" --action redact --severity high --destinations "ai_chatbots,ai_coding"

policy remove

Remove a policy by ID.

bleep policy remove block_critical

policy toggle

Enable or disable a policy by ID without deleting it.

bleep policy toggle redact_high

pattern list

List all built-in and custom detection patterns with their ID, name, category, severity, and enabled state.

bleep pattern list
bleep pattern list --json

pattern add

Add a custom detection pattern. Supports two types: regex (single regular expression) and section (multi-field PII block detection).

# Regex pattern
bleep pattern add --id my_rule --name "My Rule" --regex "SECRET-\w+" --severity HIGH

# Section pattern (multi-field PII detection)
bleep pattern add --id customer --name "Customer PII" --pattern-type section \
    --field "Name|Full Name:any_text" \
    --field "ID:digits" \
    --field "Phone:phone" \
    --field "Email:email"

Section field value types: any_text, digits, phone, email, date, custom_regex. For custom_regex, append the regex after a second colon: --field "Code:custom_regex:[A-Z]{2}[0-9]{5}"

Section patterns match per-line: any line matching a field label + value type is redacted individually. Pattern CRUD is Individual only. Enterprise endpoints receive patterns from the admin server.

pattern update

Update an existing custom pattern. Only the specified fields are changed — omitted fields remain unchanged. Works for both regex and section patterns.

bleep pattern update my_rule --name "Updated Rule Name"
bleep pattern update my_rule --regex "NEW_SECRET-\w+" --severity CRITICAL
bleep pattern update my_rule --enabled false

# Update section pattern fields
bleep pattern update customer --field "Name:any_text" --field "ID:digits" --field "SSN:digits"

Pattern CRUD is Individual only. Enterprise endpoints receive patterns from the admin server.

pattern remove

Remove a custom pattern by ID.

bleep pattern remove my_rule

pattern toggle

Enable or disable a pattern by ID without deleting it.

bleep pattern toggle my_rule

destination list

List all destination categories with their ID, description, risk level, and domain count.

bleep destination list
bleep destination list --json

destination add

Add a custom destination category for grouping domains by risk level. Policies can target specific destination categories.

bleep destination add --id custom_ai --description "Custom AI Service" --risk-level high --domains "api.custom.com,chat.custom.com"

Destination CRUD is Individual only. Enterprise endpoints receive destinations from the admin server.

destination update

Update an existing custom destination category. Only the specified fields are changed — omitted fields remain unchanged.

bleep destination update custom_ai --description "Updated AI Service"
bleep destination update custom_ai --risk-level critical --domains "api.new.com,chat.new.com"

Destination CRUD is Individual only. Enterprise endpoints receive destinations from the admin server.

destination remove

Remove a custom destination category by ID.

bleep destination remove custom_ai

destination toggle

Enable or disable a destination category by ID without deleting it.

bleep destination toggle custom_ai

blocklist add

Add an item to the encrypted blocklist. Blocklist values are stored encrypted at rest and never displayed in plaintext.

bleep blocklist add --label "Production DB password" --value "s3cr3t!" --category password --severity CRITICAL
bleep blocklist add --label "Internal project name" --value "Project Falcon" --category custom
bleep blocklist add --label "DB Password" --value "secret" --redaction-style mask
bleep blocklist add --label "Project" --value "falcon" --redaction-style fixed --redaction-text "[CLASSIFIED]"

blocklist list

List all blocklist items. Shows labels and categories but never reveals the actual values.

bleep blocklist list
bleep blocklist list --json

blocklist remove

Remove a blocklist item by ID.

bleep blocklist remove a1b2c3d4-...

blocklist toggle

Enable or disable a blocklist item by ID.

bleep blocklist toggle a1b2c3d4-...

stats

Show violation statistics: counts by severity, by pattern, by destination, and over time.

bleep stats
bleep stats --timeframe 24h
bleep stats --timeframe 7d --json

violations list

List recent violations with details including timestamp, severity, pattern, action taken, and destination.

bleep violations list
bleep violations list --json --severity HIGH --from 2026-03-01

violations export

Export violations to a file in CSV or JSON format. Useful for compliance reporting and audits.

bleep violations export --output /tmp/violations.csv
bleep violations export --output /tmp/violations.json --format json

violations count

Show a summary count of violations, optionally filtered by severity.

bleep violations count
bleep violations count --severity CRITICAL

config get / config set

Read or write configuration values. Changes take effect on next start.

# Operating mode
bleep config get mode
bleep config set mode enforcing

# Maximum request body size to scan (MB)
bleep config get scan-body-size
bleep config set scan-body-size 50

# App configuration (JSON object with boolean toggles)
bleep config get app-config
bleep config set app-config '{"docker":false,"pip":false}'

scan

Test-scan a string against all detection patterns without sending it through the DNS redirect service. Useful for testing policies and patterns.

bleep scan "My AWS key is AKIAIOSFODNN7EXAMPLE"
bleep scan "Call me at 555-123-4567, my SSN is 123-45-6789"

Returns all matches with pattern name, severity, and the matched substring.

ca info

Show CA certificate details: subject, fingerprint, expiry, and whether it is trusted by the system.

bleep ca info

ca export

Export the CA certificate to a PEM file. Useful for distributing the CA to other machines or adding to custom trust stores.

bleep ca export --output /tmp/bleep-ca.pem

ca trust

Install the Bleep CA certificate into the system trust store. Requires root/sudo.

sudo bleep ca trust

ca untrust

Remove the Bleep CA certificate from the system trust store. Requires root/sudo.

sudo bleep ca untrust

env

Print environment variables for CA certificate trust configuration. Use with eval to apply in the current shell.

# Apply CA trust env vars to current shell
eval $(bleep env)

# Write a persistent drop-in file for all users
sudo bleep env --install
# Creates /etc/profile.d/bleep-ca.sh

# Remove the drop-in file
sudo bleep env --uninstall

The --install flag writes /etc/profile.d/bleep-ca.sh so CA trust variables (like NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, etc.) are set for all login shells automatically.

diag

Generate a diagnostic report for troubleshooting. Collects protection status, configuration, CA info, DNS settings, recent logs, and system information into a plain text file.

bleep diag
bleep diag -o /tmp/bleep-diag.txt

The diagnostic bundle never includes sensitive data (blocklist values, license keys, or violation content). Send it to support when reporting issues.

update

Self-update from the download manifest. Downloads the latest Linux CLI binary, verifies it, and atomically replaces the current binary. Requires sudo when installed to /usr/local/bin.

# Check for update, download, and replace binary
sudo bleep update

# Only check if an update is available (don't download)
bleep update --check

uninstall

Completely remove Bleep from the system. Stops the daemon, restores original DNS settings, unconfigures applications, removes the CA certificate from the trust store, removes the environment profile drop-in, disables the systemd service, and deletes the data directory and binary. Enterprise: also unenrolls from the admin server.

# Preview what will be removed (requires --yes to execute)
bleep uninstall

# Completely remove Bleep
sudo bleep uninstall --yes

# Remove but keep the data directory (~/.local/share/bleep)
sudo bleep uninstall --keep-data --yes

enroll

Enroll this device with a Bleep admin server. After enrollment, the device syncs policies, domain lists, and settings from the server. Violations are reported back to the admin dashboard.

bleep-enterprise enroll --server http://admin-server:8081 --token YOUR_ENROLLMENT_TOKEN

Enrollment is a one-time operation. The device stores the server URL and credentials locally. After enrollment, run bleep-enterprise up to start protection.

unenroll

Remove enrollment from this device. Stops syncing with the admin server and clears server credentials. The service will stop reporting violations.

bleep-enterprise unenroll

Shared commands available on Enterprise

The enterprise binary also supports these commands from the shared reference above:

• config get/set — supports app-config and scan-body-size keys (mode is server-managed)
• violations list / violations export / violations count — with --severity, --from, and --to filters

Silent enrollment

If an enrollment-pending.json file exists in the data directory at startup, the enterprise binary automatically enrolls using its contents without requiring manual enroll. This is used by the admin dashboard's mass deployment scripts to enroll devices unattended.