Skip to content

Getting started

Install

wspkit is published on PyPI and supports Python 3.10 and newer.

pip install wspkit

That installs both the wspkit Python library and the wsp command-line client.

If you're working from a checkout, an editable install works the same way:

pip install -e .

Try the CLI

With nothing else configured, wsp runs a built-in workflow tool that uses Python's venv module to manage real on-disk environments.

# Confirm the install.
wsp --help

# Create a virtual environment named "scratch" using the host's Python 3.12.
wsp environment/create --name scratch --python-version 3.12

# List what's there.
wsp environment/list

# Pull the full details of one.
wsp environment/get --id <env-id>

# Run a command inside it. Use --params-json - to pass an argv array.
echo '{"id": "<env-id>", "argv": ["python", "-V"]}' \
  | wsp environment/execute --params-json -

# Tear it down.
wsp environment/delete --id <env-id>

The CLI prints the JSON result of each call to stdout on success, the JSON-RPC error object to stderr on failure, and chooses an exit code based on the response — see Exit codes.

State for the fallback tool lives under ${WSPKIT_STATE_DIR} if you set it, otherwise under the standard XDG / LOCALAPPDATA location. Pointing WSPKIT_STATE_DIR at a temp directory is the recommended way to isolate experiments.

Drive a tool you wrote

Two paths, depending on whether you want a runtime dependency on wspkit:

  • Programmatic: import wspkit, build a HandlerRegistry, register your Python callables, and call run_stdio. This is the right choice when your tool is already in Python and a small dependency is acceptable. Continue with Embed wspkit in a workflow tool.
  • Config_File: ship a TOML or JSON file that maps WSP method names to Python dotted paths or external commands; consumers run python -m wspkit --config <path>. This is the right choice when you want zero runtime coupling to wspkit, or when your handlers live in a different language. Continue with Ship a Config_File.

Next steps

  • Read the Protocol overview to understand the request/response shapes and the data model.
  • Read the Lifecycle page to understand how the initialize / shutdown / exit handshake gates everything else.
  • Skim WSP methods for the per-method parameter and result schemas.