> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate the Celesto SDK and CLI

> Authenticate Celesto SDK and CLI calls with the CELESTO_API_KEY environment variable, direct credentials, or the saved CLI login session.

Celesto uses an API key to identify your project and authorize SDK or CLI requests. You can save the key once for CLI commands, set it in your environment for SDK code, or pass it directly when you create a computer client.

## Save your key for the CLI

If you use the `celesto` CLI, save your key one time and reuse it for every command:

```bash theme={null}
celesto auth login
```

The command prompts for your API key and stores it in your operating system's secure credential store: Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux.

Manage the saved key with:

```bash theme={null}
celesto auth status
celesto auth logout
```

<Tip>
  The saved key is scoped to the Celesto API URL. If you point the CLI at a different environment with `--base-url` or `CELESTO_BASE_URL`, sign in again for that URL.
</Tip>

## API key lookup order

The CLI resolves the API key in this order:

1. `--api-key` flag
2. `CELESTO_API_KEY` environment variable
3. `.env` file in the current directory
4. Key saved by `celesto auth login`

<View title="Python" icon="python">
  ## Use an environment variable

  ```bash theme={null}
  export CELESTO_API_KEY="your-api-key"
  ```

  List computers with the environment key:

  ```python auth.py theme={null}
  from celesto import Computer


  computers = Computer.list()
  print(len(computers))
  ```

  ## Pass the key in code

  Pass `api_key` when you need to select credentials explicitly:

  ```python auth_explicit.py theme={null}
  import os

  from celesto import Computer


  computers = Computer.list(api_key=os.environ["CELESTO_API_KEY"])
  print(len(computers))
  ```
</View>

<View title="TypeScript" icon="js">
  `Computer.create()`, `Computer.get()`, `Computer.list()`, and `Computer.listTemplates()` resolve credentials automatically. The SDK checks these sources in order and uses the first one that has a value:

  1. `token` or `apiKey` passed in the client config
  2. `CELESTO_API_KEY` environment variable
  3. `CELESTO_API_KEY` in a `.env` file in the current working directory
  4. Key saved by `celesto auth login`

  If none of them produce a key, the SDK throws a `CelestoError` telling you to run `celesto auth login` or set `CELESTO_API_KEY`.

  ## Use an environment variable

  ```bash theme={null}
  export CELESTO_API_KEY="your-api-key"
  ```

  List computers with the environment key:

  ```ts auth.ts theme={null}
  import { Computer } from "@celestoai/sdk";

  const computers = await Computer.list();
  console.log(computers.length);
  ```

  ## Use a local `.env` file

  Create a `.env` file next to your entry point and add it to `.gitignore`:

  ```bash .env theme={null}
  CELESTO_API_KEY="your-api-key"
  ```

  The SDK reads `.env` from `process.cwd()` when `CELESTO_API_KEY` is not already set in the shell, so the same `Computer.list()` call works without any extra setup.

  ## Use CLI-saved credentials

  Install the CLI and sign in once. The SDK falls back to the key saved in your operating system's secure credential store when no other source is set:

  ```bash theme={null}
  pip install celesto
  celesto auth login
  ```

  ## Pass the key in code

  Pass `token` when you need to select credentials explicitly. Explicit credentials take precedence over every other source:

  ```ts auth-explicit.ts theme={null}
  import { Computer } from "@celestoai/sdk";

  const token = process.env.CELESTO_API_KEY;
  if (!token) {
    throw new Error("Set CELESTO_API_KEY before running this script.");
  }

  const computers = await Computer.list({}, { token });
  console.log(computers.length);
  ```

  ## Resolve credentials manually

  The SDK exports the same resolution helpers it uses internally, so you can reuse them in your own tooling:

  * `resolveCelestoApiKey(options?)` walks the environment, `.env`, and CLI-saved key and returns the first match, or `undefined` if none are set.
  * `resolveClientConfig(config?, options?)` returns a `ClientConfig` with `token` populated, preserving any explicit `token` or `apiKey` you already passed. It throws `CelestoError` with `MISSING_CREDENTIALS_MESSAGE` when no credentials are available.

  ```ts resolve.ts theme={null}
  import { resolveCelestoApiKey, resolveClientConfig } from "@celestoai/sdk";

  const apiKey = await resolveCelestoApiKey();
  console.log(apiKey ? "Found a Celesto API key" : "No credentials configured");

  const config = await resolveClientConfig();
  console.log(`Using token ending in ${config.token?.slice(-4)}`);
  ```
</View>