> ## 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`

## Verify which credential a command uses

Each API key is bound to a single organization. Because the lookup order reads `.env` from the current working directory, the same command can target a different organization depending on where you run it. Run `celesto auth status` to see exactly which key and organization CLI commands use from your current directory:

```bash theme={null}
celesto auth status
# API URL:      https://api.celesto.ai/v1
# Credential:   your saved login (system keyring)
# Organization: Acme Research (org_123)
```

The output reports:

* **API URL**: the endpoint commands target. Pass `--base-url` to check the credential saved for a different environment.
* **Credential**: the exact source the key came from, such as the `CELESTO_API_KEY` environment variable, a `.env` file, or your saved login.
* **Organization**: the organization the resolved key is bound to.

When a `.env` file in the current directory holds a different key than your saved login, `celesto auth status` names both organizations and tells you how to switch. Every other CLI command prints a one-time warning on stderr in that situation, naming the `.env` file that overrides the saved login. The warning goes to stderr, so `--json` output on stdout stays parseable.

To use your saved login instead of the `.env` key, run the command from another directory or pass `--api-key` explicitly.

Destructive commands also name the organization they act on: `celesto computer delete` includes it in the confirmation prompt, and `celesto computer stop` includes it in the result message. `--force` and `--json` skip the organization lookup, so scripted calls make no extra request.

<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>


## Related topics

- [Celesto SDK for sandboxed computers and agents](/cloud/overview.md)
- [Get started with the Celesto SDK](/cloud/quickstart.md)
- [Run Pi coding agent in the cloud](/cloud/guides/pi-coding-agent.md)
- [Celesto CLI reference](/cloud/cli.md)
- [Sandbox an OpenAI agent with Celesto or SmolVM](/cloud/openai-agents.md)