Command reference
Every public sp command. Use --json on API-backed commands; see Output contract. sp --help and sp <command> --help list the same commands from the installed binary.
Install and set up
| Command | Synopsis |
|---|---|
version | Print the CLI version. sp -v and sp --version do the same; sp version --json gives an envelope |
| setup | Point sp at a backend; optionally install the shared web workbench (Linux) |
doctor | Check the backend, the workbench engine and the shared web workbench — see Install — check the installation |
upgrade | Upgrade the CLI, the Java agent and the workbench engine — see Install — upgrade |
code | Start the workbench in the terminal, or sp code web in the browser — see Install — web workbench |
Lifecycle (recommended)
Job-oriented commands that follow record-and-replay order:
| Command | Synopsis |
|---|---|
| demo | start, traffic, replay, status, stop — Travel OTA demo stack |
| agent | download, command — install jar and JVM flags |
| record | case list — recorded entry cases before replay |
| diagnose | replay, trace — bundled investigation workflows |
Platform
Connect, authenticate, manage apps and policies, run replay plans.
| Command | Synopsis |
|---|---|
| config | Profiles, URL, init |
| auth | Login, whoami, refresh |
| app | List, create, agent status, recent replays |
| policy | Recording, mock, compare YAML policies |
| replay | Run, status, statistics, report, stop, rerun plans |
| health | Cluster health |
| tenant | Softprobe Cloud: tenant API key for agents |
| tunnel | Softprobe Cloud: reverse tunnel so replays reach a service on your machine |
Investigation
Recorded data, traces, and replay failures.
| Command | Synopsis |
|---|---|
| record | Query recordings and completeness |
| trace | Find traces by business attributes |
| logs | Correlated logs by trace_id — see Concepts and IDs |
| replay case | List cases, metadata, mock tree |
| replay diff | Diff artifacts, compare results |
| extraction-rule | Business attribute extraction rules |
Investigation commands support --out-dir, --page, and --limit unless noted.
Administration
Groups, system config, diagnostics.
| Command | Synopsis |
|---|---|
| group | User groups and app grants |
| grant | App grant listing (grant list) |
| system | System config keys |
| ops | Storage and schedule diagnostics |
sp recorder and sp config legacy no longer exist; see sp logs — removed commands and sp config.
Global flags
text
--json Machine-readable stdout (required for agents)
--profile Config profile name
--api-url Override backend URL
--token Override JWT (else SP_TOKEN / config)
--config Extra config file (JSONC overlay)
--quiet Suppress non-error stderr
--out-dir Directory for artifact files
--page Page number (investigation list commands)
--limit Page size / max itemsCheat sheet
bash
sp config init && sp auth login --email u@c.com --code 123456 --json
sp doctor --json
sp app create my-svc --json
curl -fsSL -o sp-agent.jar https://install.softprobe.ai/artifacts/agent/latest/sp-agent.jar
sp agent command --app <appId> --agent-jar ./sp-agent.jar --json # copy startCommand into your run script
sp record case list --app <appId> --since -1h --json
sp replay run --app <appId> --env http://your-service:8080 --from -24h --json
sp replay status <planId> --watch --json
sp diagnose replay <planId> --out-dir .sp-work --json