Use the wsp CLI

wsp is the command-line client that ships with wspkit. It performs the per-invocation lifecycle for you (initialize → method → shutdown → exit), prints the JSON result of each call to stdout, and chooses an exit code based on the response.

Three modes

wsp runs in one of three modes, picked by the top-level flags:

• --tool ARGV... — launches the supplied argv as the WSP server and routes the call through it. Use this when you have a workflow tool that knows how to run as a WSP server (because it embedded wspkit directly, or because it implements WSP itself).
• --config PATH — launches python -m wspkit --config PATH as the WSP server. Use this with the Config_File flow.
• No flag — runs the built-in fallback workflow tool in-process. Use this when you just want to manage venv-backed environments without setting anything else up.

--tool and --config are mutually exclusive; passing both is a usage error and exits with status 2.

Subcommands

Every WSP method has a corresponding subcommand:

initialize and shutdown are not exposed as user-facing subcommands — they're wrapped around every call automatically.

Each subcommand exposes one --<param> flag per parameter on the WSP method, with snake_case field names spelled in kebab-case. For example, environment/create accepts --name and --python-version.

Passing parameters

There are three ways to set request parameters:

1. Per-flag: wsp environment/create --name scratch --python-version 3.12
2. JSON on stdin: echo '{"name":"scratch","python_version":"3.12"}' | wsp environment/create --params-json -
3. Both: the JSON on stdin sets defaults; flags shadow JSON entries for the same key. Flags left at their default of None do not shadow the JSON entry, so you can JSON-supply a value and have it survive even when the corresponding flag exists on the parser.

The JSON form has a 1 MiB cap. Anything larger is rejected with a usage error and status 2.

Output and exit codes

On success, wsp writes the JSON-RPC result to stdout as a JSON document followed by a newline, and exits with status 0.

On failure, the JSON-RPC error object goes to stderr and wsp chooses an exit code based on the code:

See Exit codes for the rationale.

Timeouts

wsp enforces two 30-second budgets per invocation:

• Launch: the child server has 30 seconds to start.
• Per-call: each request has 30 seconds to receive a response.

Exceeding either prints a one-line error to stderr and exits with status 1.

Termination

When wsp exits — for any reason — it sends shutdown and exit to its child server (if it spawned one), waits up to 10 seconds for the child to terminate gracefully, and then proc.kill()s it. You don't have to babysit child processes.

Examples

Listing environments managed by the fallback

wsp environment/list

[
  {"id": "env-1f0eafbb96d3", "name": "scratch", "python_version": "3.12"}
]

Creating an environment with the fallback

wsp environment/create --name scratch --python-version 3.12

{
  "id": "env-1f0eafbb96d3",
  "name": "scratch",
  "python_version": "3.12",
  "interpreter_path": "/.../wspkit/fallback/envs/env-1f0eafbb96d3/bin/python",
  "installed_packages": [],
  "extra": {}
}

Driving a Config_File-based tool

wsp --config my-tool.toml environment/list

Executing a command in an environment

The --argv field is an array of strings, so use --params-json - to pass it:

echo '{"id": "env-1f0eafbb96d3", "argv": ["python", "-V"]}' \
  | wsp environment/execute --params-json -

{"exit_code": 0, "stdout": "Python 3.12.4\n", "stderr": ""}

State directory

The fallback workflow tool persists its environment registry under:

• ${WSPKIT_STATE_DIR} if you set it.
• ${XDG_STATE_HOME:-~/.local/state}/wspkit/fallback/ on POSIX otherwise.
• %LOCALAPPDATA%\wspkit\fallback\ on Windows otherwise.

Pointing WSPKIT_STATE_DIR at a temp directory is the recommended way to isolate experiments.