Softprobe CLI

Appearance

Quickstart ​

End-to-end record-and-replay flow. All examples use --json; omit it for human-readable tables when the CLI supports them.

Prerequisites ​

  • sp on PATH
  • Softprobe Cloud subscription OR self-hosted sp-boot backend running
  • sp-agent.jar available to attach to the Java service under test
  • A Java service you can start with JVM flags and send traffic to

1. Setup ​

Choose your deployment mode. The sp CLI will automatically initialize your configuration on first use.

For Softprobe Cloud, you do not need to install or run a local backend. Simply run the interactive login:

bash
# Start interactive setup and login
sp auth login

The CLI will:

  1. Ask you to select Softprobe Cloud.
  2. Prompt you to get your authentication code from https://app.softprobe.ai/settings/cli.
  3. Automatically write your configuration and point to the unified backend https://api.softprobe.ai.

For non-interactive environments (CI/CD/automated scripts), simply export your credentials:

bash
export SP_API_URL=https://api.softprobe.ai
export SP_TOKEN=<your-jwt-token>

Option B: Self-Hosted / Local Developer ​

If you are running the Softprobe backend on your own private network or local workstation:

bash
# Start interactive setup and select Self-Hosted
sp auth login

The CLI will:

  1. Ask you to select Self-Hosted / Local Dev.
  2. Prompt for your endpoint URL (defaults to http://127.0.0.1:8090).
  3. Save the endpoint. Since self-hosted deployments do not require authentication, you are ready to go immediately!

Or manually bypass the setup via environment variables:

bash
export SP_API_URL=http://127.0.0.1:8090

After setting up, verify your connection and environment health:

bash
sp setup doctor --json

2. Create an app ​

Register the service under test:

bash
sp app create order-service --json

Save data.appId. The same id must be used by the Java agent as sp.app.id.

3. List the app ​

Confirm the app exists:

bash
sp app list --json

Example data shape:

json
{
  "items": [
    { "appId": "a1b2c3d4e5f67890", "appName": "my-app", "agentStatus": "online" }
  ]
}

4. Set recording policy ​

Apply recording policy before starting the app with the agent:

bash
sp policy recording validate -f recording.yaml --json
sp policy recording apply -f recording.yaml --json

On success, data.valid is true. On validation errors, exit 1 with structured error details.

If users will search by business identifiers such as orderId, configure extraction rules before generating traffic:

bash
sp extraction-rule apply --app a1b2c3d4e5f67890 -f extraction-rules.yaml --json

5. Install the agent ​

Download the jar version bundled with your sp-boot release (default path under XDG data home):

bash
sp agent download --json
# writes ${XDG_DATA_HOME:-~/.local/share}/softprobe/agent/sp-agent.jar

Or build locally from sp-agent-java/sp-agent-jar/ and pass --agent-jar.

6. Run the app with the agent in record mode ​

Get copy-paste JVM flags (or use --format shell for a multiline script only):

bash
sp agent command --app a1b2c3d4e5f67890 --app-jar target/order-service.jar --json

Use data.startCommand or data.startCommandMultiline from the envelope. Override storage/API hostnames when storage is not colocated with sp-boot:

bash
sp agent command --app a1b2c3d4e5f67890 \
  --storage-host storage.example.com \
  --config-host storage.example.com \
  --json

Check that the backend sees the agent heartbeat, then send representative traffic through the running service:

bash
sp app status a1b2c3d4e5f67890 --json
curl -sS http://127.0.0.1:8080/api/orders/ORD-123

Expected data.status: online.

7. List recorded cases ​

List cases recorded for the app and time window:

bash
sp record case list --app a1b2c3d4e5f67890 --since -1h --json

If extraction rules are configured, you can also find a recorded case by business id:

bash
sp trace find \
  --app a1b2c3d4e5f67890 \
  --attr-name orderId \
  --attr-value ORD-123 \
  --json

Use the returned traceId to inspect the recording:

bash
sp record trace <traceId> --json
sp record completeness --trace-id <traceId> --json

8. Set replay policy ​

Mock policy controls which dependencies are mocked during replay. Compare policy controls which differences matter.

bash
sp policy mock validate -f mock.yaml --json
sp policy mock apply -f mock.yaml --json
sp policy compare validate -f compare.yaml --json
sp policy compare apply -f compare.yaml --json

9. Establish Reverse WebSocket Tunnel (Remote Control Plane only) ​

If your Softprobe control plane is hosted in the cloud (SaaS) but your application is running locally on your workstation, the cloud scheduler cannot directly hit http://localhost:8080.

Before initiating the replay plan, open a separate terminal window and establish a reverse WebSocket tunnel to bridge replay traffic:

bash
sp tunnel --app a1b2c3d4e5f67890 --port 8080
  • Success Indicator: The terminal prints ✔ Reverse tunnel connected successfully!. Keep this process running during replay.
  • (Note: If your sp-boot backend is running fully locally, you can skip this step).

10. Create a replay plan ​

Now that recorded cases exist and replay policy is set (and your tunnel is online, if using a SaaS backend), create a replay plan. The CLI checks for recorded cases in the window first; if none exist, it fails with NO_RECORDED_CASES unless you pass --allow-empty:

bash
sp replay run \
  --app a1b2c3d4e5f67890 \
  --env http://localhost:8080 \
  --from -24h \
  --enable-mock \
  --json

Capture data.planId (or data.replayPlanId) from the response.

11. Check replay results ​

bash
sp replay status plan-abc123 --watch --json
sp replay case list --plan plan-abc123 --json

--watch polls until terminal state (FINISHED, FAILED, CANCELLED).

For failed cases in one step:

bash
sp diagnose replay plan-abc123 --failed-only --out-dir .sp-work --json

Or manually: sp replay case list --plan plan-abc123 --failed --json then sp replay diff get <diffId> --out-dir .sp-work --json.

Full walkthrough: Diagnose replay failure.