Configure the SDK
Set the Haystack Platform API key, API URL, and default workspace to use with the SDK.
About This Task
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
The SDK reads these settings:
| Variable | What it is | Default | Required |
|---|---|---|---|
API_KEY | Your Haystack Enterprise Platform API key. | None | Yes |
API_URL | Base URL of the platform API. A trailing version segment (/api/v1, /v2) is stripped, so pasting a full URL works. | https://api.cloud.deepset.ai | No |
DEFAULT_WORKSPACE_NAME | Haystack Platform workspace used when a command takes no --workspace-name. | None (login suggests default) | No |
ASYNC_CLIENT_TIMEOUT | Timeout in seconds for the async client. | 300 | No |
Where Settings Come From
The SDK resolves each setting separately, in this order. The first source that supplies a value takes precedence:
- Explicit arguments: a CLI flag such as
--workspace-name, or a parameter passed in Python. - Environment variables set in your shell.
- A local
.envin the directory you run the command from. - The global
~/.haystack-enterprise/.envwritten bylogin. - Built-in defaults, where a setting has one.
Because each setting resolves on its own, a local .env doesn't replace the global one. Any key you leave out of the local file still comes from the global file. This means a project can override just the workspace in its own .env and keep using the API key from login.
If a local .env exists when you run login, the CLI warns you that the local file takes precedence over the global file it's about to write.
Prerequisites
- Haystack Platform API key. You can get an API key from API Keys in Haystack Enterprise Platform. For more on API keys, see Generate an API Key.
- Haystack Platform API URL. The base URL of the Haystack Platform API. The default is
https://api.cloud.deepset.ai. - Haystack Platform workspace name. The default workspace name is
default.
Configure the SDK With the CLI
Log In
-
Run the following command to log in:
haystack-enterprise login -
When prompted, enter your API key, API URL, and the name of the workspace you want to set as default for all operations.
By default, login prints a link and a code. Open the link in a browser on any device, confirm the code, and allow the CLI access. Then choose a default workspace. Because nothing has to reach back to your machine, this works over SSH, VPNs, remote development boxes, and containers. The CLI stores a session that refreshes itself in ~/.haystack-enterprise/credentials.json. To log in through a browser on the same machine instead, run haystack-enterprise login --no-device. To write an API key and workspace without any prompts, for example in CI, run haystack-enterprise login --api-key <YOUR_API_KEY> --workspace-name <YOUR_WORKSPACE>. For all options, see CLI Reference.
Running the login command creates a global configuration file at ~/.haystack-enterprise/.env that stores the API key, API URL, and default workspace name.
Choose an Organization and Workspace During Browser Login
When you sign in through your browser, login asks you to choose an organization if you belong to more than one, and then a default workspace. The workspace list contains only the workspaces you have access to. If you have access to only one workspace, login selects it without asking.
At each prompt, type the number next to an entry or its name. If an entry matches both a name and a number, the name wins, so a workspace named 2 stays reachable. If you enter a value that isn't in the list, login asks again.
Authorize the CLI in Your Browser
On platforms that don't offer OAuth login, haystack-enterprise login --no-device opens an Authorize page in your browser. The page lets you give the CLI an API key without copying one by hand.
- Run
haystack-enterprise login --no-device. The CLI opens the page in your browser and waits for it to respond. - If you're not logged in to Haystack Enterprise Platform, log in. You return to the Authorize page afterward.
- Select the workspace the CLI should use.
- Click Authorize.
The page creates a personal API key for the selected workspace and sends it to the CLI on your machine. The key is named after the machine you ran login on, expires, and has the same role you have in that workspace. When the page tells you to return to your terminal, the CLI has written the key and workspace to ~/.haystack-enterprise/.env. You can revoke the key under Settings > API Keys.
If the page reports an invalid link or can't create the key, see Troubleshoot Configuration.
Log Out
Logging out deletes the global configuration file. To do this, run:
haystack-enterprise logout
Configure the SDK With the Python API
Pass credentials directly:
from haystack_enterprise_sdk import PipelineClient
client = PipelineClient(api_key="...", api_url="https://api.cloud.deepset.ai")
If you omit them, the same cascade applies.
Use a Different Environment
To point at a non-production environment, set API_URL in your shell, in a local .env, or by answering n to the URL question during login:
export API_URL=https://api.dev.cloud.dpst.dev
Turn Off the Upgrade Hint
After a command finishes in an interactive terminal, the CLI checks PyPI at most once a day and prints a hint on stderr when a newer haystack-enterprise-sdk release exists. The result of the check is cached in ~/.haystack-enterprise/version_check.json.
To turn the hint off, set HAYSTACK_ENTERPRISE_NO_UPDATE_CHECK to any non-empty value in your shell, for example in your shell profile:
export HAYSTACK_ENTERPRISE_NO_UPDATE_CHECK=1
The CLI also skips the check when CI=true and when stderr isn't a terminal. For the upgrade commands, see Install the SDK.
Examples
login is interactive and has no flags. To change the saved defaults, run login again or edit ~/.haystack-enterprise/.env. To override settings for one command, pass a flag or set an environment variable.
- Override the workspace for one command:
haystack-enterprise validate pipeline.py --workspace-name my-workspace
- Set the API key, API URL, and workspace in your shell:
export API_KEY=my-api-key
export API_URL=https://api.dev.cloud.dpst.dev
export DEFAULT_WORKSPACE_NAME=my-workspace
What To Do Next
- Check the SDK version installed:
haystack-enterprise --version
Related Information
- Install the SDK
- Troubleshoot Configuration: what to do when a command hits the wrong environment or reports a missing key.
- CLI Reference
Was this page helpful?