Quick Reference
The Haystack Enterprise SDK on one page. For every command and flag, see the CLI Reference.
On Windows, or when haystack-enterprise isn't on your PATH, replace it with python -m haystack_enterprise_sdk.cli.
Setup
uv tool install haystack-enterprise-sdk # install the CLI
haystack-enterprise --version # confirm it's installed
haystack-enterprise login # store API key, URL, and workspace
haystack-enterprise logout # remove the stored config
Settings resolve in this order (first match wins): CLI flag → environment variable → local .env → global ~/.haystack-enterprise/.env → default.
The Deploy Flow
Four steps, all reading the same file:
# 1. Build locally with Haystack (no CLI)
# 2. Validate against the platform
haystack-enterprise validate pipeline.py
# 3. Run in the platform sandbox
haystack-enterprise run pipeline.py --query "What is deepset?"
# 4. Deploy as a service
haystack-enterprise deploy pipeline.py my-service
# Check the service any time
haystack-enterprise service-status my-service
Pipelines
# Validate a specific entrypoint with an explicit interpreter
haystack-enterprise validate pipeline.py --entrypoint my_pipeline --python .venv/bin/python
# Run with explicit inputs from a file and save the output
haystack-enterprise run pipeline.py --inputs @inputs.json --output result.json
# Deploy a managed service with sizing and a revision comment
haystack-enterprise deploy pipeline.py my-service --managed --cpu 2 -m "New embedder"
# Deploy and get a shareable chat UI link
haystack-enterprise deploy pipeline.py my-service --share
# Preview the transformed YAML without deploying (no credentials needed)
haystack-enterprise deploy pipeline.py my-service --dry-run --output out.yaml
Common pipeline flags: --entrypoint (which pipeline in the file), --python (interpreter that loads it), --io-config (pin the input/output mapping), --skip-validation, --skip-activation.
Files
# Upload a folder (all supported types; add --recursive for subfolders)
haystack-enterprise upload ./my-files
# Limit to specific types and overwrite same-named files
haystack-enterprise upload ./my-files --use-type .md --use-type .docx --write-mode OVERWRITE
# List and filter files
haystack-enterprise list-files
haystack-enterprise list-files --odata-filter "key eq 'value'"
# Download files, including metadata
haystack-enterprise download --workspace-name my-workspace --include-meta
# Check upload sessions
haystack-enterprise list-upload-sessions
haystack-enterprise get-upload-session <session-id>
Write modes: KEEP (default, keeps both), OVERWRITE (replaces), FAIL (rejects duplicates).
Global Flags
These work on nearly every command:
| Flag | Effect |
|---|---|
--api-key | Override the stored API key. |
--api-url | Override the platform URL. |
--workspace-name | Override the default workspace. |
--verbose / -v | Show INFO and DEBUG logs. Goes before the command name. |
--version | Print the SDK version and exit. |
The io-config File
Pin the input/output mapping and pipeline settings in <pipeline>.io.yaml (picked up automatically). deploy --share can write it for you:
# pipeline.io.yaml
inputs:
query:
- retriever.query
outputs:
answers: answer_builder.answers
pipeline_output_type: chat
Common Fixes
| Symptom | Fix |
|---|---|
API key is required | haystack-enterprise login, or pass --api-key. A local .env can shadow the global one. |
command not found | Add the uv tools directory to your PATH, or use python -m haystack_enterprise_sdk.cli if that Python has the SDK installed. |
ModuleNotFoundError: No module named 'haystack' | Pass --python with the interpreter that has Haystack, or install the deploy extra. |
| Query pipeline won't deploy | Map a query input and one output. Rename sockets or pin a <pipeline>.io.yaml. |
| Files uploaded but missing | Ingestion lags. Check with list-upload-sessions and get-upload-session. |
For the full list, see Troubleshooting.
Related Information
Was this page helpful?