Skip to main content

Keploy CLI Commands​

View as Markdown
FreeTeamsScaleEnterprise

Usage​

keploy [command] [flags]

You can use --help, -h flag for all the commands to see available flag options and their purpose.

Commands and Flags​

Here are some examples of how to use some common flags:

CommandFlags Available
record-c, --command, --config-path, --containerName, --metadata, -n, --networkName, --passThroughPorts, -p, --path, --proxy-port, --debug
test--apiTimeout, -c, --command, --config-path, --containerName, -d, --delay, --mongoPassword, -n, --networkName, --passThroughPorts, -p, --path, --proxy-port, -t, --testsets, --debug, --removeUnusedMocks, --skip-coverage, --ignoreOrdering, --disable-line-coverage, --proto-dir, --proto-file, --proto-include
gen (Deprecated)--sourceFilePath, --testFilePath,--coverageReportPath,--testCommand,--coverageFormat,--expectedCoverage,--maxIterations,--testDir,--llmBaseUrl,--model,--llmApiVersion
normalize-p, --path, --test-run, --tests
report--test-sets, -t, -p, --path, --report-path, -r, --body
sanitize--test-sets, -t, -p, --path
config--generate,-p, --path

record​

The record mode in Keploy allows the user to record Keploy testcases from the API calls. The recorded testcases and generated mocks are then saved in the keploy directory in the current working directory.

Usage:
keploy record [flags]
Available flags:
  • -c, --command string - Command required to start the user application.
keploy record --command "node src/app.js"

In the command above, node src/app.js is the command which starts the user application.

  • --config-path string - Path to the Keploy configuration file. The default is ".".
keploy record -c "node src/app.js" --config-path "./config-dir/"

In the above command, config-dir is the directory in the CWD where the Keploy configuration file keploy.yaml is stored.

  • --container-name string - Name of the docker container in which the user application is running.
keploy record -c "docker compose up" --container-name "my-app-container"

Podman: on Linux, with the Keploy that install.sh installs (v3.8.60 or later), an application started in rootful Podman with podman run or podman compose works the same way: keploy record -c "podman compose up" --container-name "my-app-container". See Platform requirements for what podman compose needs.

  • --metadata string - Key-value pairs to be added as metadata in the config.yaml file. If a name key is provided, it will be used as the test set name.
keploy record -c "node src/app.js" --metadata "name=mac,env=production,service=gin-mongo,version=2.0.0,team.members[0]=alice,team.members[1]=bob,team.members[2]=carol,labels[0]=canary,labels[1]=stable,config.timeout=30s,config.timeout=60s,complex=a\\,b\\,c\\,d,database.urls[0]=db1.internal,database.urls[1]=db2.internal,database.urls[2]=db3.internal,mode=fast,mode=slow"
keploy record -c "node src/app.js" --metadata "name=mac,env=production,service=gin-mongo,version=2.0.0,team.members[0]=alice,team.members[1]=bob,team.members[2]=carol,labels[0]=canary,labels[1]=stable,config.timeout=30s,config.timeout=60s,complex=a\\,b\\,c\\,d,database.urls[0]=db1.internal,database.urls[1]=db2.internal,database.urls[2]=db3.internal,mode=fast,mode=slow"

Note: If the same key is used multiple times, the last occurrence will be used.

  • - n, --network-name string - Name of the docker network in which the user application is running.
keploy record -c "docker compose up" --container-name "my-app-container" -n "my-app-network"
  • --pass-through-ports uints - Ports of outgoing dependency calls to be ignored as mocks and passed through to the actual dependency. The default is no ports.
  • -p, --path string - Path to the local directory where the recorded testcases and generated mocks are to be saved.
keploy record -c "node src/app.js" -p "./tests"

In the above command, tests is the directory in the CWD where the recorded testcases and generated mocks are to be stored.

  • --proxy-port uint32 - Port to choose to run Keploy as a proxy. The default is 16789.
keploy record -c "node src/app.js" --proxy-port 8080
  • --capture-packets - Capture the raw network packets on Keploy's proxy ports and write them into each test set's directory as traffic.pcap, with the TLS session keys in sslkeys.log next to it, so that Wireshark or tshark can decrypt the TLS traffic.
keploy record -c "node src/app.js" --capture-packets
tshark -r keploy/test-set-0/traffic.pcap -o tls.keylog_file:keploy/test-set-0/sslkeys.log
Ubuntu 26.04

Ubuntu 26.04 confines tshark with an AppArmor profile (/etc/apparmor.d/tshark). Apart from its own data files, tshark may read only files that the user running it owns under /tmp, /var/tmp or ~/tmp. Given the files in keploy/test-set-0/, it stops with "You don't have permission to read the file". It also skips a key log file that it may not read without saying so, and then shows the TLS traffic still encrypted. Copy both files first, as the user who runs tshark:

d=$(mktemp -d)
cp keploy/test-set-0/traffic.pcap keploy/test-set-0/sslkeys.log "$d"/
tshark -r "$d/traffic.pcap" -o "tls.keylog_file:$d/sslkeys.log"

If you run sudo tshark, make the copies with sudo cp, so that root owns them.

  • --debug - To start recording testcases with debug mode enabled.
keploy record -c "node src/app.js" --debug

test​

The test mode in Keploy allows the user to run the recoded testcases from the API calls and execute assertion. A detailed report is produced after the tests are executed and it's then saved in the yaml format in keploy/reports directory in the current working directory.

Usage:
keploy test [flags]
Available flags:
  • --api-timeout uint - Timeout in seconds for calling user application. The default is 5 seconds.
keploy test -c "node src/app.js" --api-timeout 10
  • -c, --command string - Command required to start the user application.
keploy test -c "node src/app.js"

In the command above, node src/app.js is the command which starts the user application.

  • --config-path string - Path to the Keploy configuration file. The default is ".".
keploy test -c "node src/app.js" --config-path "./config-dir/"

In the above command, config-dir is the directory in the CWD where the Keploy configuration file keploy.yaml is stored.

  • --container-name string - Name of the docker container in which the user application is running.
keploy test -c "docker compose up" --container-name "my-app-container"
  • -d, --delay uint - Delay in seconds to run user application. The default is 5 seconds.
keploy test -c "node src/app.js" --delay 10
  • --mongo-password string - Authentication password for mocking MongoDB connection. The default password is "default123".
keploy test -c "node src/app.js" --mongo-password "my-password"
  • - n, --network-name string - Name of the docker network in which the user application is running.
keploy test -c "docker compose up" --container-name "my-app-container" -n "my-app-network" -d 9
  • --pass-through-ports uints - Ports of outgoing dependency calls to be ignored as mocks and passed through to the actual dependency. The default is no ports.

  • -p, --path string - Path to the local directory where the recorded testcases and generated mocks are saved.

keploy test -c "node src/app.js" -d 10 --path "./tests"

In the above command, tests is the directory in the CWD where the recorded testcases and generated mocks are saved.

  • --proxy-port uint32 - Port to choose to run Keploy as a proxy. The default is 16789.
keploy test -c "node src/app.js" --proxy-port 8080
  • -t, --test-sets strings - To specify which specific testsets are to be executed. The default is all testsets.
keploy test -c "node src/app.js" -t "test-set-1,test-set-3" --delay 10
  • --debug - To start executing testcases with debug mode enabled.
keploy test -c "node src/app.js" --delay 10 --debug
  • --remove-unused-mocks - To remove unused mocks from mock file. The default is false.
keploy test -c "node src/app.js" --delay 10 --remove-unused-mocks
  • --ignore-ordering - Ignore the order of elements in an array for a response, with the default value being true.
keploy test -c "node src/app.js" --delay 10 --ignore-ordering
  • --skip-coverage - skip code coverage computation while running the test cases

  • --disable-line-coverage - skip the line by line code coverage preview of a JavaScript application, but display the total coverage.

keploy test -c "node src/app.js" --delay 10 --disable-line-coverage
  • --jacoco-agent-path - Only applicable for test coverage for Java projects. You can override the jacoco agent jar by providing its path

  • --proto-dir string - Path of the directory where all protos of a service are located. Used for GRPC test cases to enable better deterministic and proper comparison of protobuf responses.

keploy test -c "node src/app.js" --proto-dir "./protos"
  • --proto-file string - Path of main proto file. Used for GRPC test cases to enable better deterministic and proper comparison of protobuf responses. Either --proto-file or --proto-dir must be provided for GRPC tests.
keploy test -c "node src/app.js" --proto-file "./protos/main.proto"
  • --proto-include stringArray - Path of directories to be included while parsing import statements in proto files. This is optional and used for GRPC test cases when proto files have import dependencies.
keploy test -c "node src/app.js" --proto-file "./protos/main.proto" --proto-include "./protos/common,./protos/shared"

Note for GRPC Tests: When running GRPC test cases, it's recommended to provide proto information using either --proto-file or --proto-dir flags. If proto information is not provided, Keploy will use basic canonical matching of the protoscopic textual format of GRPC response body, which may be less accurate than proto-based comparison.

gen​

Deprecated: This command is deprecated.

The gen cmd in Keploy allows user to generate unit tests using LLM Models.

Usage:
keploy gen [flags]
Available flags:
  • sourceFilePath - Path to the source file for which tests are to be generated.

  • testFilePath - Path where the generated tests will be saved.

  • coverageReportPath - Path to generate the coverage report.

  • testCommand - Command to execute tests and generate the coverage report.

  • coverageFormat - Type of the coverage report by default report is in "cobertura" format.

  • expectedCoverage - Desired coverage percentage by default it is set to be at 100%.

  • maxIterations - Maximum number of iterations for refining tests (default 5).

  • testDir - Directory where tests will be written.

  • llmBaseUrl - Base url of the llm.

  • model - Specifies the AI model to use by default it uses "gpt-4o" model.

  • llmApiVersion - API version of the llm if any.

normalize​

The normalize cmd in Keploy allows user to change the response of the testcases according to the latest test run response that is executed by the user, this is useful when the API response of the testcases are changed due to code change or any other intentional change in the application.

This command is now “risk-aware” to prevent accidental acceptance of breaking API changes. By default, it will automatically update tests that failed with Low or Medium risk, but it will refuse to normalize any test that failed with a High risk, printing a warning instead.

Usage:
keploy normalize [flags]
Available flags:
  • -p, --path string - Path to the local directory where the recorded testcases and generated mocks are to be saved.
keploy normalize -p "./tests"

In the above command, tests is the directory in the CWD where the recorded testcases and generated mocks are to be stored.

  • --test-run string - by default normalization considers the latest test-run to change the response of the testcases but if user want to do it for a particular test-run this flag can be used.
keploy normalize -p "./tests" --test-run "test-run-10"
  • --tests string - by default normalization considers all the testcases for normalization but if user want to normalize only few particular testcases or testsets this flag can be used
keploy normalize -p "./tests" --test-run "test-run-10" --tests "test-set-1:test-1 test-2, test-set-2, test-set-3, test-set-4:test-3"
  • --allow-high-risk - Allow normalization of high-risk test failures. This flag overrides the default safe behavior and updates all failed tests, including those with breaking changes.
keploy normalize --allow-high-risk

report​

The report command in Keploy is used to display a detailed summary of test results. It can show a compact table-style diff or full body diffs (with colorized JSON), and it can read from the latest test run or a specific report file.

Usage:
keploy report [flags]
Available flags:
  • -t, --test-sets strings - Testsets to report, e.g., --test-sets "test-set-1, test-set-2". If omitted, all test sets in the latest run are considered.
keploy report -t "test-set-1"
  • -p, --path string - Path to the local directory where generated testcases/mocks are stored. Default is ".".
keploy report -p "./keploy-tests"
  • --report-path, -r string - Absolute path to a specific report file to display results from (must point to a file, not a directory). You can still combine this with other flags like --summary or --test-case.
keploy report --report-path "/home/user/my-app/keploy/reports/test-run-1.yaml"
  • --full - Show full diffs instead of the default compact table view. For JSON bodies, this produces colorized expected/actual comparisons.
keploy report -t "test-set-1" --full
  • --summary - Print only a summarized view (grand totals and per-test-set table with time taken). Useful for a quick dashboard-style overview. Can be combined with -t/--test-sets and --report-path.
keploy report --summary
  • --test-case strings (alias: --tc) - Filter output to specific test case IDs.
keploy report --test-case "test-1"

Notes

  • By default, report shows only failed tests with a compact, human-readable diff (status, headers—including trailers/content-length where applicable—and body changes).
  • Use --full to see the complete expected vs actual bodies (with JSON colorization).
  • --summary prints just the totals and a per-test-set table, optionally restricted with -t/--test-sets.
  • When --report-path is provided, Keploy reads that file directly. Legacy files that contain only a tests list are supported.

templatize​

The templatize cmd allows the user to templatize important fields in the testcases who's values are used in the request of testcases and that may change in the future.

Usage:
keploy templatize [flags]

config​

The config command in Keploy is used to generate the Keploy Configuration File i.e. keploy.yaml. The generated configuration file is created in the current working directory.

Usage:
keploy config [flags]
Available flags:
  • --generate - Generate a new keploy configration file.
keploy config --generate
  • -p, --path string - Path to the local directory where the Keploy Configuration File will be stored. The default is ".".
keploy config --generate --path "./config-dir/"

In the above command, config-dir is the directory in the CWD where the Keploy configuration file keploy.yaml is to be stored.

example​

The example command in Keploy is designed to illustrate the usage of Keploy in various scenarios, showing its capabilities with different types of applications and setups. Below are examples for using Keploy with Golang, Node.js, Java, and Docker applications.

Usage:
keploy example [flags]
Available Flags:
  • --customSetup - Displays commands tailored for custom user-defined setups.

mock​

keploy mock records the calls your own test suite makes to its dependencies, and replays them so the suite runs with the dependencies off. See Mock your tests for the whole flow.

Usage:
keploy mock record -c "<your test command>"
keploy mock replay -c "<your test command>"
keploy mock status
CommandWhat it does
keploy mock recordRuns your test command and records the outgoing calls it makes into a mock set.
keploy mock replayRuns your test command with those calls answered from the mock set. --on-miss decides what an unrecorded call gets.
keploy mock statusReads the repository and prints a NEXT block: what the recordings prove and the command to run next. --json prints it as JSON.
keploy mock uploadUploads a mock set to the Keploy registry.
keploy mock downloadDownloads a mock set from the Keploy registry.

With KEPLOY_PROVEN=1 set, keploy mock record also judges every test it records, and keploy mock replay runs only the tests it kept. These commands run only with the switch:

CommandWhat it does
keploy mock explain <test>Says why a test is skipped or run, with its evidence and its recorded calls.
keploy mock quarantine <test> --reason "<why>"Skips a test in CI, with your reason, until it's recorded again. --undo runs it again.
keploy mock checkReads the recordings offline and names each mistake a hand edit made, with its file, line and fix.
keploy mock judgeJudges the recordings again, for example after a Keploy upgrade.

See Prove each test offline.

login​

keploy login signs you in to your Keploy account. It opens a sign-in page in your browser and waits for you to approve it.

Usage:
keploy login
Available flags:
  • --no-wait - Print the sign-in link and code and exit instead of waiting. Then run keploy login --finish to collect the session once you've approved it. Use this on a machine with no browser, or from a coding agent, whose shell shows a command's output only when it exits.
  • --finish - Collect the session for a sign-in that keploy login --no-wait started. It waits up to 70 seconds for your approval, and you can run it again until the code expires.
  • --api-key string - Use this Keploy API key for the command instead of KEPLOY_API_KEY. In CI, set KEPLOY_API_KEY from a secret instead of signing in.
  • --k8s-proxy-url string - For a self-hosted cluster: check the API key (from --api-key, KEPLOY_API_KEY or a login already saved, or asked for in a terminal) at this k8s-proxy, then save the key and the URL in ~/.keploy/cred.yaml, readable by you only. Later commands then need neither KEPLOY_API_KEY nor KEPLOY_K8S_PROXY_URL. A key the proxy refuses saves nothing. See Log in once on your own machine.
  • --show - Print the API key (its last 4 characters only) and the k8s-proxy URL commands here use, where each one comes from (a flag, an environment variable, keploy.yml, or the saved login), and whether k8s-proxy-auth mode is on and why, without signing in.

keploy logout signs you out, and removes a saved self-hosted login (the API key and the k8s-proxy URL in ~/.keploy/cred.yaml).

status​

keploy status reads the keploy/ folder of the service you run it in and prints a NEXT block for the record and test loop: where things stand and the command to run next. keploy mock status does the same for keploy mock. Add --json to print the block as JSON.

keploy status

app​

keploy app create creates the Keploy app the repository records into, or reuses the app with the same name, and saves its id as mock.appId in keploy.yml. Commit keploy.yml with it.

keploy app create --name orders-api

Without --name, the app is named after the git repository's folder, or the current folder outside a repository.

skill​

keploy skill install installs Keploy's skills into the coding agents it finds on your machine: Claude Code, Cursor, Codex, Antigravity and GitHub Copilot.

Usage:
keploy skill install
Available flags:
  • --agent strings - Install for these agents only, for example --agent claude-code,cursor.
  • --all - Install for every supported agent, whether or not Keploy finds it.
  • --project - Install into the current repository instead of your home folder.
  • --dry-run - List every file the install would write, and write nothing.

update​

The update command installs the latest Keploy release over the binary you are running.

Usage:
keploy update

Automatic updates​

Keploy keeps itself on the latest release. Before a command starts, Keploy checks for a newer release, at most once an hour, or 10 minutes after a check that failed. The check takes at most 3 seconds. A check that fails, on a machine that is offline or when the release server doesn't answer within those 3 seconds, is made again by the first command 10 minutes or more later. When there is a newer release, Keploy downloads it, verifies its SHA-256 checksum, replaces the binary, and runs your command on the new version. Your command runs once, on the new version. Commands that start during the install wait for it, and they run on the new version too.

When the update can't happen, Keploy prints a warning on stderr and runs your command on the version you have. This covers a machine that is offline, a release server that can't be reached, a binary you can't write to, a download that fails its checksum, and a binary that another Keploy run is using. A failed install is tried again after an hour. An install that stops making progress can hold your command for up to 10 minutes before Keploy gives up on it. Pressing Ctrl+C during an update stops your command too: it doesn't start.

The install script puts Keploy where your user can replace it: ~/.keploy/bin, which it adds to your PATH in your shell's startup file. A terminal that was already open needs export PATH="$HOME/.keploy/bin:$PATH". For a shell other than bash or zsh, the script prints the line to add yourself instead: for fish, set -U fish_user_paths $HOME/.keploy/bin $fish_user_paths, run once; for csh and tcsh, setenv PATH "$HOME/.keploy/bin:$PATH" in ~/.cshrc, or in ~/.tcshrc when you have one and your shell is tcsh, as csh on macOS is. On macOS, every install goes to ~/.keploy/bin. On Linux, three installs keep /usr/local/bin: one run as root, one in a CI pipeline, and a 2.x version pinned with -v. With -noRoot, those three go to ~/.keploy/bin too. The script knows a CI pipeline by its environment: GitHub Actions, GitLab CI, CircleCI, Travis CI, Buildkite, Drone, AppVeyor, Jenkins, TeamCity, Bitbucket Pipelines, AWS CodeBuild, Azure Pipelines, Bamboo, GoCD, or any system that sets CI=true. In any other script that installs in one shell and runs Keploy in another, pass -isCI.

An install from before this change is in /usr/local/bin, which only root can write to. A run that isn't root can't update there, so it prints the warning on each command and stays on its version. The warning says how to move to a folder you own:

curl -fsSL https://keploy.io/install.sh | bash

The script then prints the command that removes the old binary. To stay in /usr/local/bin, run sudo keploy update for each release.

A binary in ~/.keploy/bin isn't on the path sudo searches, so sudo keploy doesn't find it. Keploy asks for sudo itself when a command needs it. To run it as root yourself, use sudo -E env PATH="$PATH" keploy.

Keploy never replaces a binary that a run is using. Every run of a command holds a lock beside the binary until it ends, so all the Keploy processes of a run are one version. While a run is under way, other commands on that machine warn and run the version installed, and keploy update refuses and says that a run is using the binary. A long keploy record holds updates off until it ends. The next command after the last run ends installs the update.

CI pipelines and service-account keys update the same way as any other run.

To keep a pipeline on the version it installed, or to run where the release server can't be reached, set KEPLOY_DISABLE_AUTO_UPDATE:

export KEPLOY_DISABLE_AUTO_UPDATE=1
keploy test -c "<command to run your app>"

With KEPLOY_DISABLE_AUTO_UPDATE set to 1, true, yes, or on, Keploy doesn't check for a release and doesn't install one. keploy update still installs the latest release when you run it.

Plain sudo drops the variable, so run sudo -E env PATH="$PATH" keploy to keep it.

A version you install with the install script's -v flag is also replaced by the latest release at the first command, unless you set the variable.

Keploy doesn't replace its own binary in these cases:

  • Keploy Docker image: pull a newer image.
  • Homebrew, Nix, or Snap: Keploy prints a warning and runs on the version you have. Update through the package manager.
  • VS Code extension: the extension installs and tracks its own binary. Keploy only prints a notice that a newer release is available.
  • Self-hosted runs: these runs reach only your k8s-proxy, so Keploy doesn't check for a release. A run is self-hosted when --k8s-proxy-auth, --k8s-proxy-url, KEPLOY_K8S_PROXY_AUTH, KEPLOY_K8S_PROXY_URL, cloud.k8sProxyAuth or cloud.k8sProxyUrl in keploy.yml, or a login saved by keploy login --k8s-proxy-url turns the mode on.
  • Builds from an organization's release channel: a build published under keploy.io/ent/dl/org/<organization>/ has a version with a suffix, such as 3.8.112-4f2a9c1d. Keploy never replaces it with a public release, and keploy update leaves it alone too. Install new builds from the same channel.