Skip to content

CLI Reference

This document provides an overview of the CLI. The CLI is organized into a single command with grouped parameters, allowing you to configure and run the proxy with various network fault simulations, execute test scenarios defined in a file or launch a local demo server.

Commands

run

Run the proxy with fault injection enabled. This command applies the specified network faults to HTTP requests and tunnel streams.

scenario

Execute a predefined fault injection scenario. This command includes additional subcommands for building scenarios from OpenAPI specification.

agent

Analyze scenario results and suggest code changes using LLM.

demo

Run a simple demo server for learning purposes, with various fault simulation options available.

Global Options

These options apply across all commands.

  • --log-file <file>
    Path to a file where fault can append new logs during its execution.
    Example: --log-file fault.log

  • --log-stdout
    Flag enabling logs to be printed to the standard output.
    Default: Disabled
    Example: --log-stdout

  • --log-level <level>
    Logging level which must follow the format set by cargo.
    Default: info,tower_http=debug
    Example: --log-level warning

Observability Options

These options apply across all commands:

run Command Options

Fault injection parameters are grouped into sections based on the type of network fault. Each section allows you to enable or disable a fault and configure its properties.

UI Options

These options define how the UI is setup on fault's output:

  • --no-ui
    Disable entirely the terminal UI and make the output fully silent.

  • --tail
    Enable tailing of intercepted traffic into the console.
    Default: Disabled

Proxy Configuration Options

These options define how to configure the proxy started by fault:

  • --duration <value>
    How long to run the proxy process for. See here for the supported syntax
    Default: unlimited Example: --duration 60s Example: --duration 10m

  • --proxy-address <address>
    Listening address for the proxy server.
    Default: 127.0.0.1:3180
    Example: --proxy-address 192.168.12.45:8090

  • --proxy <proto-def>
    Target host(s) to proxy (can be specified multiple times). You may also set * to tell fault you want to impact any upstream.
    Example: --upstream example.com Example: --upstream '*' Example: --upstream=*

Note

Upstream hosts are currently ignored by TCP proxies.

Upstream Hosts Options

  • --upstream <host>
    Target host(s) for HTTP proxying (can be specified multiple times). You may also set * to tell fault you want to impact any upstream.
    Example: --upstream example.com Example: --upstream '*' Example: --upstream=*

Remote Plugins Options

These options define the remote plugins to forward traffic to.

  • --grpc-plugin <address>
    The address of a gRPC plugin. This can be set multiple times.
    Example: --duration http://0.0.0.0:50051

Stealth Configuration Options

These options configure the stealth mode of the fault's proxy.

Info

Stealth mode is currently only supported on Linux hosts. Therefore you will not see these options on other systems.

This option addresses recent Linux kernels.

Note

Upstream hosts are currently ignored when traffic is redirected via the eBPF programs.

  • --stealth
    Enable stealth mode using eBPF.
    Default: Disabled
    Example: --stealth

  • --capture-process <procname>
    Process name captured by the eBPF program (requires --stealth).
    Example: --capture-process curl

  • --ebpf-proxy-ip <ip>
    IP address to bind the eBPF proxy to. If unset, uses the same as the default proxy address (requires --stealth).
    Example: --ebpf-proxy-ip 192.168.1.26

  • --ebpf-proxy-port <port>
    Port to bind the eBPF proxy to. If unset, uses a random port (requires --stealth).
    Example: --ebpf-proxy-port 47070

  • --ebpf-proxy-iface <iface>
    Interface to attach the eBPF programs to. Defaults to the interface associated to the eBPF proxy IP (requires --stealth).
    Example: --ebpf-proxy-iface eth0

Latency Options

Learn more about the latency fault.

  • --with-latency
    Enable latency fault injection.
    Default: Disabled

  • --latency-per-read-write
    Apply latency on each read or write operation rather than once.
    Default: Disabled

  • --latency-side <side>
    Side to apply the latency fault. Options: client, server
    Default: server

  • --latency-direction <direction>
    Direction to apply the latency fault. Options: ingress, egress, both
    Default: both

  • --latency-distribution <distribution>
    Latency distribution type (uniform, normal, pareto, pareto_normal).
    Default: normal

  • --latency-mean <value>
    Mean latency in milliseconds (positive float) (requires --latency-distribution normal).
    Example: --latency-mean 300

  • --latency-stddev <value>
    Standard deviation in milliseconds (non-negative float) (requires --latency-distribution normal).
    Example: --latency-stddev 20

  • --latency-shape <value>
    Distribution shape parameter (non-negative float) (requires --latency-distribution pareto|pareto_normal).
    Example: --latency-shape 20

  • --latency-scale <value>
    Distribution scale parameter (non-negative float) (requires --latency-distribution pareto|pareto_normal).
    Example: --latency-scale 20

  • --latency-min <value>
    Minimum latency for uniform distribution (non-negative float) (requires --latency-distribution uniform).
    Example: --latency-min 20

  • --latency-max <value>
    Maximum latency for uniform distribution (non-negative float) (requires --latency-distribution uniform).
    Example: --latency-max 50

  • --latency-sched <value>
    Intervals scheduling when to apply the fault (require --duration whhen using relative schedule).
    Example: --latency-sched "start:30s,duration:60s" Example: --latency-sched "start:5%,duration:40%" (requires --duration)

Bandwidth Options

Learn more about the bandwidth fault.

  • --with-bandwidth
    Enable bandwidth fault injection.
    Default: Disabled

  • --bandwidth-side <side>
    Side to apply the bandwidth fault. Options: client, server
    Default: server

  • --bandwidth-direction <direction>
    Direction to apply the bandwidth fault. Options: ingress, egress, both
    Default: ingress

  • --bandwidth-rate <value>
    Bandwidth rate as a positive integer.
    Default: 1000

  • --bandwidth-unit <unit>
    Unit for the bandwidth rate (options: Bps, KBps, MBps, GBps).
    Default: Bps

  • --bandwidth-sched <value>
    Intervals scheduling when to apply the fault (require --duration whhen using relative schedule).
    Example: --bandwidth-sched "start:30s,duration:60s" Example: --bandwidth-sched "start:5%,duration:40%" (requires --duration)

Jitter Options

Learn more about the Jitter fault.

  • --with-jitter
    Enable jitter fault injection.
    Default: Disabled

  • --jitter-direction <direction>
    Direction to apply the jitter fault. Options: ingress, egress, both
    Default: ingress

  • --jitter-amplitude <value>
    Maximum jitter delay in milliseconds (non-negative float).
    Default: 20.0

  • --jitter-frequency <value>
    Frequency of jitter application in Hertz times per second (non-negative float).
    Default: 5.0

  • --jitter-sched <value>
    Intervals scheduling when to apply the fault (require --duration whhen using relative schedule).
    Example: --jitter-sched "start:30s,duration:60s" Example: --jitter-sched "start:5%,duration:40%" (requires --duration)

DNS Options

  • --with-dns
    Enable DNS fault injection.
    Default: Disabled

  • --dns-rate <value>
    Probability to trigger a DNS failure (non-negative float).
    Default: 0.5

  • --dns-sched <value>
    Intervals scheduling when to apply the fault (require --duration whhen using relative schedule).
    Example: --dns-sched "start:30s,duration:60s" Example: --dns-sched "start:5%,duration:40%" (requires --duration)

Packet Loss Options

Learn more about the Packet Loss fault.

  • --with-packet-loss
    Enable packet loss fault injection.
    Default: Disabled

  • --packet-loss-direction <direction>
    Direction to apply the packet loss fault. Options: ingress, egress, both
    Default: ingress

  • --packet-loss-sched <value>
    Intervals scheduling when to apply the fault (require --duration whhen using relative schedule).
    Example: --packet-loss-sched "start:30s,duration:60s" Example: --packet-loss-sched "start:5%,duration:40%" (requires --duration)

HTTP Response Options

Learn more about the HTTP Error fault.

  • --with-http-response
    Enable HTTP response fault injection (return a predefined response).
    Default: Disabled

  • --http-response-direction <direction>
    Direction to apply the HTTP response fault. Options: ingress, egress, both
    Default: ingress

  • --http-response-status <code>
    HTTP status code to return (e.g., 500, 503).
    Default: 500

  • --http-response-body <string>
    Optional response body to return.
    Default: (none)

  • --http-response-trigger-probability <value>
    Probability (0.0 to 1.0) to trigger the HTTP response fault.
    Default: 1.0 (always trigger when enabled)

  • --http-response-sched <value>
    Intervals scheduling when to apply the fault (require --duration whhen using relative schedule).
    Example: --http-response-sched "start:30s,duration:60s" Example: --http-response-sched "start:5%,duration:40%" (requires --duration)

Blackhole Options

Learn more about the Blackhole fault.

  • --with-blackhole
    Enable blackhole fault injection.
    Default: Disabled

  • --blackhole-direction <direction>
    Direction to apply the blackhole fault. Options: ingress, egress, both
    Default: ingress

  • --blackhole-sched <value>
    Intervals scheduling when to apply the fault (require --duration whhen using relative schedule).
    Example: --blackhole-sched "start:30s,duration:60s" Example: --blackhole-sched "start:5%,duration:40%" (requires --duration)

Usage Examples

Running the Proxy with Multiple Faults

fault run \
  --proxy-address "127.0.0.1:3180" \
  --with-latency --latency-mean 120.0 --latency-stddev 30.0 \
  --with-bandwidth --bandwidth-rate 2000 --bandwidth-unit KBps

scenario Command Options

A fault scenario is a file containing test scenarios to execute automatically by fault generating report and result files for further analysis.

Proxy Configuration Options

  • --proxy-address <address>
    Listening address for the proxy server.
    Default: 127.0.0.1:3180
    Example: --proxy-address 192.168.12.45:8090

Run Options

  • --scenario <file>
    Path to a YAML scenario file.
    Example: --scenario ./scenario.yaml

  • --report <file>
    Path to a file where to save the final repor.
    Example: --scenario ./report.yaml

Generate Options

  • --scenario <path>
    Path to a YAML scenario file or directory. If you pass a directory, the scenarios will be split in individual files per endpoint.
    Example: --scenario ./scenario.yaml

  • --spec-file <file>
    Path to an OpenAPI specification file (or use --spec-url).
    Example: --spec-file ./openapi.json

  • --spec-url <url>
    URL to an OpenAPI specification file (or use --spec-file)._
    Example: --spec-url http://localhost/openapi.json

agent Command Options

A fault agent is an AI agent using LLM to analyze code and scenario results to help you make appropriate changes.

Common Options

These options define the LLm parameters of the agent.

Note

Currently, only OpenAI is enabled. Next release will support Ollama and Open Router.

  • --llm-client <client>
    Select the LLM client to use.
    Default: open-ai

  • --llm-prompt-reasoning-model <model>
    Reasoning model to use.
    Default: o4-mini

  • --llm-prompt-chat-model <model>
    Chat prompt model to use.
    Default: gpt-4.1-mini

  • --llm-embed-model <model>
    Embedding model to use.
    Default: text-embedding-3-small

Code Review Options

Ask fault to review your source code.

  • --report <file>
    Path to the file where the report is saved.
    Default: code-review-report.md

  • --advices-report <file>
    Path to report generated by the scenario-review command (optional).
    Default: scenario-review-report.md

  • --results <file>
    Path to the scenario results JSON file.
    Default: results.json

  • --index <file>
    Path to the DuckDB index to use for source code indexing.
    Default: /tmp/index.db

  • --source-dir <directory>
    Path to the top-level source-code directory to bring more context.

  • --source-lang <lang>
    Language of the source code: python, rust, java....

Scenario Review Options

Ask fault to review a scenario run's results.

  • --report <file>
    Path to the file where the report is saved.
    Default: scenario-review-report.md

  • --results <file>
    Path to the scenario results JSON file.
    Default: results.json

  • --role <role>
    Role to generate the review with: developer or sre.
    Default: developer

demo Command Options

A simple demo server listening for HTTP requests.

Demo Options

  • --address <addr>
    IP address to bind the the demo server to.
    Default: 127.0.0.1
    Example: --address 192.168.2.34

  • --port <port>
    Port to bind to.
    Default: 7070
    Example: --port 8989