Search…
⌃K

CLI & SDK

Get up and running with Gretel's CLI and SDK.
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. For Apple Silicon (M1/M2) users, Python 3.9+ is required due to several third party dependencies.

Installation

To get started, you will need to setup your environment and install the appropriate packages.
The most straightforward way to install the gretel-client CLI and SDK is with pip:
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

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.
CLI
SDK
To begin the CLI configuration process, use the command:
gretel configure
This will walk you through some prompts that should look similar to:
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 []:
  1. 1.
    Accept the default for the Endpoint.
  2. 2.
    The Default Runner is set for cloud. If you need to run compute on your own machine(s), change this value to local. We recommend keeping cloud as the default runner, which will utilize Gretel Cloud's auto-scaling GPU and CPU fleet to create and utilize models.
  3. 3.
    When prompted for your Gretel API Key, paste the key you created in the Gretel Console.
  4. 4.
    When prompted for your Default Project, enter a Project Name or accept the default.
Finally, you can test your configuration using the command:
gretel whoami
If the configuration is good to go, you should get back an 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, and can use the CLI without needing to re-authenticate. If you run into trouble, feel free to contact us for help!
There are a few different options to configure your Gretel Cloud connection through the SDK.
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.

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.
Gretel Python Client docs can be found here.