Authenticate the Celesto SDK and CLI

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:

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:

celesto auth status
celesto auth logout

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.

API key lookup order

The CLI resolves the API key in this order:

--api-key flag
CELESTO_API_KEY environment variable
.env file in the current directory
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:

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.

Use an environment variable

export CELESTO_API_KEY="your-api-key"

List computers with the environment key:

auth.py

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:

auth_explicit.py

import os

from celesto import Computer

computers = Computer.list(api_key=os.environ["CELESTO_API_KEY"])
print(len(computers))

Start Here

Features

Guides

Agents and Integrations

Authenticate the Celesto SDK and CLI

Save your key for the CLI

API key lookup order

Verify which credential a command uses

Use an environment variable

Pass the key in code

​Save your key for the CLI

​API key lookup order

​Verify which credential a command uses

​Use an environment variable

​Pass the key in code

Save your key for the CLI

API key lookup order

Verify which credential a command uses

Use an environment variable

Pass the key in code