Account and authentication

You need an account before you can run anything. There’s no free-standing API key to manage: the CLI holds a session for you, and the REST API authenticates with the same email and password.

Create an account

From the CLI:

distil signup

That opens the sign-up page in your browser. Create your account there, and when you’re done the browser hands the session straight back to the CLI, so you’re signed in already and there’s no separate login step.

You can also sign up at app.distillabs.ai/sign-up.

register and join are aliases for signup.

Sign in from the CLI

distil auth

This opens the sign-in page and hands the session back when you’re done. login is an alias.

On a machine with no browser, CI for example, pass the credentials directly:

distil auth --email you@example.com --password "$DISTIL_PASSWORD"

Check who you’re signed in as, or sign out:

distil whoami
distil logout

The CLI keeps its own session, in ~/.config/distillabs/token (under $XDG_CONFIG_HOME when that’s set), and refreshes it for you. A run spanning several hours won’t ask you to log in again.

Authenticating against the API

The REST API takes an access token from Cognito, minted with the same email and password. Tokens last one hour, which is shorter than a training run, so fetch one per request rather than holding it:

response = requests.get(
    "https://api.distillabs.ai/seed-datasets",
    headers={"Authorization": access_token},
)

Using the REST API has the auth() helper that mints the token, along with the rest of the helpers the API examples depend on. Don’t copy the auth block on its own. The surrounding helpers handle the error bodies where validation failures actually live.

When it doesn’t work

Not logged in or session expired. Run `distil login` to authenticate or `distil register` to create an account.

Run distil auth. If you have no account yet, distil signup first.

Invalid email or password.

Wrong credentials on distil auth --email … --password ….

Email confirmation required. Please check your email and confirm your account.

The account exists but isn’t confirmed yet. Open the confirmation email, then authenticate again.

Timed out waiting for browser authorization

The browser flow didn’t finish. Authenticate headlessly instead, with --email and --password.

A 401 from the API means the credentials are wrong. A 403 usually means the token has expired, so mint a new one. More symptoms and their fixes: Troubleshooting.

Next

Building a model, or pick your task type first with Task selection.