CLI Reference

Quickly check commands and flags you may need.

---

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

Getting Help

Run haystack-enterprise <command> --help for the exhaustive list of commands and flags, and the current defaults.

Common Flags

Three flags are accepted by nearly every command: --api-key, --api-url, and --workspace-name. They override the configuration set with the login command.

--verbose / -v turns on the SDK's INFO and DEBUG logs. It's a global option, so use it before the command name, for example: haystack-enterprise --verbose upload ./my-files.

Commands at a Glance

Command	What it does
login	Store your API key, API URL, and default workspace.
logout	Delete the stored configuration.
upload	Upload a file or folder to a workspace.
download	Download files from a workspace.
list-files	List files in a workspace.
list-upload-sessions	List upload sessions, including closed ones.
get-upload-session	Show one upload session's status.
validate	Check that a local pipeline is deployable.
run	Run a local pipeline in the platform sandbox.
deploy	Deploy a local pipeline as a service.
service-status	Show a service deployment's status.

There's also a top-level --version, which prints the installed SDK version and exits, and --verbose, described above.

Authentication

login

Prompts for the platform URL, your API key, and a default workspace, then writes them to ~/.haystack-enterprise/.env. This command is interactive and has no flags. To override settings for one command, pass --api-key, --api-url, or --workspace-name on that command, or set the matching environment variable.

haystack-enterprise login

logout

Deletes that file.

haystack-enterprise logout

version

Prints the installed SDK version and exits.

haystack-enterprise --version

Files

upload

haystack-enterprise upload ./my-files

Flag	What it does	Default
--recursive	Include subfolders.	Off. Only top-level files.
--use-type	Limit the upload to these file extensions. Repeat per type.	All supported types. Omit the flag to upload every supported type in the folder.
--write-mode	KEEP, OVERWRITE, or FAIL when a name already exists.	KEEP
--blocking / --no-blocking	Wait until the files appear in the platform.	On (--blocking).
--timeout-s	How long to wait when blocking.	None. Waits indefinitely.
--show-progress / --no-show-progress	Progress bar.	On.
--enable-parallel-processing	Upload in parallel.	Off.

For details and examples, see Upload Files.

download

Downloads files from a Haystack Platform workspace to your local machine.

haystack-enterprise download --workspace-name my-workspace

Flag	What it does	Default
--file-dir	Where to write the files locally.	None, the files are downloaded to the current working directory.
--name	Only files whose name matches.	None, all files are downloaded.
--odata-filter	Only files matching an OData metadata filter.	None, all files are downloaded.
--include-meta	Also download each file's metadata.	True
--batch-size	Files fetched per request.	50

list-files

Prints a list of files that exist in a Haystack Platform workspace.

haystack-enterprise list-files
haystack-enterprise list-files --name "report.pdf"
haystack-enterprise list-files --odata-filter "key eq 'value'"

Flag	Effect	Default
--name	Filter by file name.	None. Lists all files.
--odata-filter	Filter by metadata, OData syntax.	None. Lists all files.
--batch-size	Files fetched per request.	10

list-upload-sessions

Prints a list of every upload session for the workspace, including closed ones.

haystack-enterprise list-upload-sessions
haystack-enterprise list-upload-sessions --is-expired

Flag	Effect	Default
--is-expired	Include expired sessions.	Off.
--batch-size	Sessions fetched per request.	10

get-upload-session

One session's status, by ID.

haystack-enterprise get-upload-session <session-id>

Pipelines

All three pipeline commands take the path to a local Python file as their first argument, and share these flags:

Flag	What it does	Default
--entrypoint	Which pipeline in the file to use, when it defines more than one.	None. Uses the single pipeline in the file.
--python	Interpreter that loads your pipeline.	Auto-detected virtual environment near the file, otherwise the current interpreter.
--io-config	YAML or JSON file with explicit inputs: and outputs: sections plus settings.	<target>.io.yaml next to the pipeline file, when it exists.
--skip-io-validation	Skip the input and output mapping checks and prompts.	Off.

validate

haystack-enterprise validate pipeline.py

Transforms the pipeline and asks the platform to check the result, without deploying. Exits with a non-zero code on blocking errors.

validate converts your pipeline into deployable YAML and sends it to the platform for checking. It doesn't deploy the pipeline. The command:

• Prints warnings and errors.
• Exits with a non-zero code if an error is blocking.
• Reports Pipeline is valid. when the pipeline is deployable.

Validation runs against the haystack-ai version your pipeline pins, not the version installed on the platform. If a component exists in one version but not the other, validation follows the version that will run your pipeline.

The first validation for each version is slow. The platform builds an environment for that version, which takes 20 to 30 seconds. If the build takes longer than the command's timeout, validate retries once. Later validations against the same version are fast.

validate never prompts you. It uses the input and output mapping it infers from your socket names, and it tells you when that mapping can't be served. To set the mapping yourself, use a config file. See The io-config File.

run

haystack-enterprise run pipeline.py --query "What is deepset?"

Flag	Effect	Default
--query	Text routed to the sockets mapped to the query input.	None. On an interactive terminal, you're prompted when you pass no --query, --set, or --inputs.
--inputs	Explicit run inputs as JSON, literal or @file.json. Wins over --query.	None
--set	Set a single input value, for example --set token=abc or --set prompt=@file.md.	None
--include-outputs-from	Limit results to specific components. Repeatable.	None. Returns all components.
--output	Write the result JSON to a file.	None. Prints to your terminal.
--retries	Retries for transient failures. 0 disables.	2

run executes your local pipeline in the platform sandbox and prints the results back in your terminal, again without deploying. Use it to check real output before committing to a service.

• --query routes text to the sockets mapped under the pipeline's query input. On an interactive terminal, you're prompted for it if you pass neither --query nor --inputs.
• --inputs passes explicit run inputs as JSON: a literal string or @path/to/file.json. The shape is the Haystack run inputs dictionary, {"component": {"socket": value}}. Explicit inputs win against anything derived from --query.
• --include-outputs-from limits the result to specific components. Repeat the option for several; it defaults to all components.
• --output writes the result JSON to a file instead of printing it.

Unlike validate and deploy, run isn't pinned to the haystack-ai version your pipeline declares. The sandbox executes against the platform's own Haystack. Use validate for the version-accurate check.

deploy

haystack-enterprise deploy pipeline.py my-service

Flag	Effect	Default
--managed	Create a provisioned service rather than serverless. Required for any sizing flag.	Off. Creates a serverless service.
--service-level, --cpu, --memory, --gpu, --min-replicas, --max-replicas, --idle-timeout	Sizing. Managed services only.	None. Unset.
--create / --no-create	Require that the service does not / does already exist.	Neither. Reuses the service if it exists, otherwise creates it.
--comment, -m	Revision comment.	Auto-generated from git when omitted.
--skip-activation	Push the revision without rolling it out.	Off. The revision is activated.
--skip-validation	Skip the pre-deploy check.	Off. The pipeline is validated.
--dry-run, --output	Print or save the transformed YAML without deploying. Needs no credentials.	Off.
--share, --share-expiration-days, --share-login-required	Create a shareable chat UI link.	Not shared. When shared, the link expires after 30 days and requires login.

See Deploy a Pipeline for the full flow.

deploy pushes your pipeline as a new revision of a service deployment. By default, it activates the revision, and for a managed service it waits for the rollout to finish.

Common options:

• The service is looked up by name first. If it exists, the revision is pushed to it. Otherwise, the service is created and the CLI tells you so. New services are serverless: they provision no workload and run the active revision per request, so there's no rollout to wait for.
• --create requires that the service doesn't exist yet. --no-create requires the service to exist and fails if it's missing, which is useful in CI to catch a mistyped service name instead of provisioning a new service.
• --managed creates a managed (provisioned) service instead. Only managed services can be sized, so --service-level, --min-replicas, --max-replicas, --cpu, --memory, --gpu, and --idle-timeout require --managed.
• --comment / -m is the comment stored on the revision, so you can tell revisions apart in the platform UI. When you omit the flag, the CLI generates a comment naming the pipeline file and, if it sits in a git repository, the current branch and commit.
• --skip-activation pushes the revision as PENDING without rolling it out.
• --skip-validation skips the pre-deploy YAML validation, which runs by default and aborts on blocking issues.
• --io-config / --skip-io-validation control the input/output mapping, the same as in validate.

If the service doesn't exist, the command creates it.

Every deployed pipeline needs to know which input receives the query and which output returns the result. If your pipeline uses the conventional socket names, deploy works this out on its own.

The conventional names are:

• query or messages for the input.
• answers, replies, or documents for the output.

If a name doesn't match, deploy asks you to choose. It asks only about the one it couldn't work out:

Which socket receives the query?
  1. greeter.name (str, mandatory)
  0. not mapped
> 1

You can list your inputs and outputs in a <pipeline>.io.yaml file, or pass them with --io-config. Then deploy runs without stopping to ask.

service-status

haystack-enterprise service-status my-service

Python API

Use the Python API to call the same workflows from your own code:

from haystack_enterprise_sdk import PipelineClient

For the concepts behind each workflow, see Deploy a Pipeline and Upload Files.

Related Information

• Quick Reference: the most common commands on one page.
• Troubleshooting