To communicate with Spell using the Python API, the first thing you need to do is create a SpellClient object.

Creating a client

The easiest and preferred way to create a SpellClient is using the from_environment() function.


Creates a SpellClient object with configuration deduced from the environment.

First, attempts to find configuration from environment variables:


The authentication token for the user.


The namespace (e.g. user or organization) in which commands should take place.


An active workflow configuration for setting the workflow context on the returned client.

Second, attempts to find configuration from an active user session of the Spell CLI.


A SpellClient object.


ClientException – an error occured.

You can also directly instantiate a SpellClient if desired.

class SpellClient(token, workflow_id=None)

A client for interacting with Spell.

  • token (str) – the authentication token to use for communicating with Spell.

  • workflow_id (int, optional) – the id of the workflow to set as the active_workflow


the active workflow for the client. All runs created will be created in the associated workflow. If the value is None, runs are not created in a workflow.



property hyper

An object for managing hyperparameter searches. See SpellClient.hyper.

property models

An object for managing models. See SpellClient.models.

property resources

An object for managing resources. See SpellClient.resources.

property runs

An object for managing runs. See SpellClient.runs.

property servers

An object for managing model servers. See spell.client.servers.ModelServersService.