Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Run a Pipeline

Learn how to run a Haystack pipeline you built locally in the Haystack Enterprise Platform sandbox to check its output, without deploying it.

About This Task​

Use the run command to check that a pipeline returns what you expect while you iterate, without creating a service.

run takes the path to the local Python file that defines your pipeline or agent (pipeline.py in the examples). When a file defines more than one pipeline instance or factory, use --entrypoint to pick one.

Your pipeline loads in your project's Python environment (an auto-detected virtual environment near the file, or the interpreter you pass with --python), so the CLI's own environment doesn't need your pipeline's dependencies installed.

info

The sandbox runs your pipeline against the platform's own version of haystack-ai, not the version your pipeline pins. A version-specific problem can show up in run but not in a deployed service, or the other way around. To check against the exact version your pipeline pins, use validate.

Prerequisites​

Run a Pipeline​

info

When using the Haystack Enterprise SDK on Windows, if haystack-enterprise isn't on your PATH, replace it with python -m haystack_enterprise_sdk.cli, for example:

haystack-enterprise validate pipeline.py

becomes

python -m haystack_enterprise_sdk.cli validate pipeline.py

In these steps, pipeline.py is the path to the local Python file that defines your pipeline or agent. Replace it with the path to your own file.

  1. Run your pipeline with a query:
haystack-enterprise run pipeline.py --query "What is deepset?"

The command prints the pipeline output as JSON. The first run may be slow while the platform builds an environment for the version of haystack-ai your pipeline pins.

The --query text is routed to the sockets mapped to the pipeline's query input. If your pipeline uses conventional socket names, the mapping is inferred. If a name doesn't match, the CLI asks you to choose the socket, or you can pin the mapping in a <pipeline>.io.yaml file. For more information, see IO Config. On an interactive terminal, the CLI prompts you for a query when you don't pass --query, --set, or --inputs.

  1. To save the output to a file instead of printing it, use --output:
haystack-enterprise run pipeline.py --query "What is deepset?" --output result.json

Use --output rather than a shell redirect (>). The CLI writes its logs to standard output, so redirecting mixes them into the JSON.

Transient failures, such as network errors, timeouts, and 429 or 5xx responses, are retried twice by default. Configuration and input errors always fail right away. Use --retries to change the number of retries, or --retries 0 to disable retrying.

Examples​

  • Pass your pipeline's own named platform inputs. Repeat --set for each one, and use @ to read a value from a file:
haystack-enterprise run pipeline.py \
  --set github_token=ghs_abc \
  --set security_prompt=@security.md
  • Run with explicit inputs from a file and save the output to a file:
# inputs.json holds a Haystack run inputs dict: {"component": {"socket": value}}
haystack-enterprise run pipeline.py --inputs @inputs.json --output result.json
  • Pass explicit runtime inputs as JSON. --inputs uses the Haystack run shape, {"component": {"socket": value}}. --set takes a platform input key, not a component socket:
haystack-enterprise run pipeline.py --inputs '{"retriever": {"top_k": 5}}'
  • Limit the results to specific components. Repeat --include-outputs-from for each one:
haystack-enterprise run pipeline.py --query "What is deepset?" --include-outputs-from retriever
  • Run a specific pipeline with your own interpreter and mapping:
haystack-enterprise run pipeline.py \
  --entrypoint my_pipeline \
  --python .venv/bin/python \
  --io-config pipeline.io.yaml
  • Run in CI by setting the CI environment variable to true. This turns off the progress animations and prints plain text.