Installation

The Gretel CLI and Python SDK are made available through both PyPi (most common) and GitHub.
We recommend using Python 3.7+ when using the CLI and SDK.
Installation
Utilize pip to install and keep your package up-to-date. This can be done by installing gretel-client as such:
$ pip install -U [--pre] gretel-client
The -U flag will ensure the most recent version is installed. Occasionally we will ship a Release Candidate (RC) version of the package. These are generally safe to install, you may optionally include this with the inclusion of the --pre flag.
If you wish to have the most recent development features, you may also choose to install directly from GitHub with the following command. This may be suggested from our Customer Success team if you are testing new features that have not been fully released yet.
$ pip install git+https://github.com/gretelai/[email protected]
Authentication
CLI
After installing the package, you should configure authentication with Gretel Cloud. This will be required in order to create and utilize any models.
If you are installing Gretel on a system that you own or wholly control, we highly recommend configuring the CLI and SDK once with our configuration assistant. If you do this once, you will be able to use the CLI and SDK without doing specific authentication before running any commands.
You may begin the configuration process with the CLI like so:
$ gretel configure
This will walk you through some prompts that should look similar to this:
Gretel.ai COPYRIGHT Notice
​
​
The Gretel CLI and Python SDK, installed through the "gretel-client"
package or other mechanism is free and open source software under
the Apache 2.0 License.
​
When using the CLI or SDK, you may launch "Gretel Worker(s)"
that are hosted in your local environment as containers. These
workers are launched automatically when running commands that create
models or process data records.
​
The "Gretel Worker" and all code within it is copyrighted and an
extension of the Gretel Service and licensed under the Gretel.ai
Terms of Service.  These terms can be found at https://gretel.ai/terms
section G paragraph 2.
​
​
​
Endpoint [https://api.gretel.cloud]:
Default Runner (cloud, local) [cloud]:
Gretel API Key [grtuf6c5****]:
Default Project []:
Some notes:
The Endpoint must be: https://api.gretel.cloud
We suggest keeping cloud as the default runner, which will utilize Gretel Cloud's auto-scaling GPU and CPU fleet to create and utilize models.
Create and acquire an API key from the Gretel Console, and supply that.
If you've created a Project, perhaps for experimentation, you may retrieve the Project Name from the Console and supply that. When running commands in the CLI and SDK, if you do not provide a specific project name, your default one will be used.
Finally, when you have completed this step, you can test your connection to Gretel Cloud like this:
$ gretel whoami
If things are successful, you should get back some output like this:
{
    "email": "[email protected]",
    "config": {
        "endpoint": "https://api.gretel.cloud",
        "api_key": "grtuf6c5****",
        "default_project_name": "my-synthetic-project",
        "default_runner": "cloud",
        "preview_features": "disabled"
    }
}
At this point, you are authenticated with Gretel Cloud and can use the CLI and SDK without needing to re-authenticate. If you run into trouble, feel free to contact us for help!
SDK
Additionally, you may configure your Gretel Cloud connection through the SDK. There are a few different options when doing things through the SDK.
First, if you are using an ephemeral environment (such as Google Colab, etc) and you only wish to configure your connection for the duration of your Python session. You can configure your connection like this:
from gretel_client import configure_session
​
configure_session(api_key="grtu****", validate=True)
​
# If in a Notebook or similar environment you should see...
​
# Using endpoint https://api.gretel.cloud
# Logged in as [email protected] ✅
Never commit code with your Gretel API key exposed! Generally you should load your Gretel API key in from some secure secrets manager or an environment variable.
​
See below for additional options if you are creating a Notebook, etc such that you can always configure API key prompting.
If you wish to maintain code that others may use, you can also use the following modification for configuring your session with Gretel Cloud. By using the prompt value, you'll be presented with a dialogue to import your API key.
from gretel_client import configure_session
​
configure_session(api_key="prompt", validate=True)
​
# If in a Notebook or similar environment you should see...
​
# Using endpoint https://api.gretel.cloud
# Logged in as [email protected] ✅
Using the prompt option will only work if you do not already have Gretel credentials saved on disk. If credentials are already found on disk, configure_session() will utilize those and validate the connection with Gretel Cloud.
Here's an example output from Google Colab:
Session authentication with Gretel Cloud
CLI and SDK Fundamentals - Previous
Introduction
Next - CLI and SDK Fundamentals
Projects
Last modified 30d ago
Copy link
Outline