CLI & SDK
Get up and running with Gretel's CLI and SDK.
We require using Python 3.9+ when using the CLI and SDK.
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/gretel-python-client@main
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]:
Artifact Endpoint [cloud]:
Default Runner (cloud, local, hybrid) [cloud]:
Gretel API Key [grtuf6c5****]:
Default Project []:
- 1.Accept the default for the Endpoint.
- 2.The Artifact Endpoint is only required for hybrid, and it should be an Azure, GCP or S3 bucket that your training data will be stored in. Leave it set to
cloudotherwise. - 3.The Default Runner is set for
cloud.If you need to run compute on your own machine(s), change this value tolocal. We recommend keepingcloudas the default runner, which will utilize Gretel Cloud's auto-scaling GPU and CPU fleet to create and utilize models.- 1.If you need to run in Hybrid mode (i.e. where the test data/models/jobs are hosted in a hybrid environment) you'll want to select
hybrid
- 4.
- 5.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",
"artifact_endpoint": "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.
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.If you want to configure your session to run in Hybrid mode, run the following as part of
configure_session:from gretel_client import configure_session
configure_session(
api_key="grtu****", validate=True,
default_runner="hybrid", artifact_endpoint="s3://my-bucket" # or gcs:// azure://
)
# If in a Notebook or similar environment you should see...
# Using endpoint https://api.gretel.cloud
# Logged in as [email protected] ✅
The hybrid environment configuration will apply to everything run with the Gretel client, including libraries like Gretel Trainer and Gretel Relational.
Last modified 2mo ago