Skip to content

SDK & CLI overview

The skyportalai package lets you work with SkyPortal outside the browser. It has an interactive terminal, commands you can script, and a Python SDK. It also ships the observability agent that you can run on your own machines and clusters.

Requirements

  • Python 3.11 or newer.
  • The current release is 0.3.1 on PyPI. The project is alpha (pre-1.0), so interfaces can still change between minor versions.
  • Source: github.com/SkyportalAi/skyportalai

Upgrading from 0.2 or earlier?

Since 0.3.0 the SKYPORTAL_* environment variables are ignored, and the skyportal command and import package are gone. Read Upgrading to 0.3 first.

What's in the package

Interface How you start it Use it for
Interactive terminal skyportalai Working with SARA from a terminal: approvals, file uploads, host and namespace scope
CLI commands skyportalai chat ..., skyportalai config ..., skyportalai kubernetes ... Scripts and CI/CD, with stable --json output
Python SDK from skyportalai import Skyportal Applications and Python automation
Observability agent skyportalai-agent Reporting experiments, hosts and Kubernetes clusters to SkyPortal. See In-cluster agent

SARA, the SkyPortal agent, runs on SkyPortal's servers. The SDK and the CLI create chats, read their status and messages, and send your approval decisions.

Install

python -m pip install skyportalai

With Poetry:

poetry add skyportalai

From a clone of the repository:

git clone https://github.com/SkyportalAi/skyportalai.git
cd skyportalai
python -m pip install -e .

The agent extra installs wandb, which the observability agent needs to read Weights & Biases run logs:

python -m pip install "skyportalai[agent]"

Sign in

skyportalai login

The CLI prints a short code and a URL, and opens the URL in your browser. Confirm the code in the browser. The terminal then saves the credential and finishes on its own.

  • --no-browser prints the URL without opening it. Use it on a remote machine.
  • --token skips the browser and asks you to paste an API key from the SkyPortal web app. API keys start with sk_. Agent tokens (agt_) only work for the observability agent and are refused here.

The credential is saved in ~/.skyportalai/credentials.json. Each time the CLI saves it on Linux or macOS, it makes the file readable only by your user. A file left by an older version keeps its permissions until it is saved again. skyportalai logout deletes it.

If ~/.skyportalai doesn't exist yet and you still have a ~/.skyportal directory from an older version, the CLI moves it to ~/.skyportalai the first time it runs. If the move fails, it keeps using ~/.skyportal and prints a warning. See Upgrading to 0.3.

For scripts and CI, skip login and put an API key in the environment:

export SKYPORTALAI_API_KEY="YOUR_API_KEY"

Keep credentials out of code

Never put real API keys, tokens, approval IDs, hostnames or other private infrastructure details in code, logs, screenshots, issues or docs.

Environment variables

Variable Read by Purpose
SKYPORTALAI_API_KEY SDK, CLI, terminal API key
SKYPORTALAI_ACCESS_TOKEN CLI, terminal Access token. Wins over SKYPORTALAI_API_KEY when both are set
SKYPORTALAI_BASE_URL SDK, CLI commands API target
SKYPORTALAI_URL CLI commands API target, used when SKYPORTALAI_BASE_URL is not set
SKYPORTALAI_ALLOW_INSECURE=1 SDK, CLI, terminal, agent Allow plain HTTP to a trusted host that is not localhost. A warning is printed
SKYPORTALAI_CONFIG_PATH CLI, terminal Use another config.yaml
SKYPORTALAI_CREDENTIALS_PATH CLI, terminal Use another credentials.json
SKYPORTALAI_HISTORY_PATH, SKYPORTALAI_LAST_CHAT_PATH Terminal Use other files for the input history and the last chat ID

The observability agent reads its own SKYPORTALAI_AGENT_* variables. See In-cluster agent.

Which API target is used

The scriptable commands (config, chat, ansible and kubernetes) pick the API target in this order:

  1. --base-url on the command line
  2. SKYPORTALAI_BASE_URL
  3. SKYPORTALAI_URL
  4. portal.base_url in ~/.skyportalai/config.yaml
  5. The deployment saved with your credential in ~/.skyportalai/credentials.json
  6. https://app.skyportal.ai

The interactive terminal and the login, ask, servers, start and github-token commands work differently. They read only portal.base_url from config.yaml, or use https://app.skyportal.ai, and they ignore --base-url and the URL environment variables. To point them at another deployment, save the URL:

skyportalai config set --base-url https://skyportal.example.com

https://skyportal.ai is treated as https://app.skyportal.ai.

Example config.yaml:

portal:
  base_url: https://app.skyportal.ai
  request_timeout: 30

request_timeout is in seconds. Use a whole number: the interactive terminal does not accept fractions.

Which credential is used

CLI commands and the interactive terminal use the first credential they find:

  1. SKYPORTALAI_ACCESS_TOKEN
  2. SKYPORTALAI_API_KEY
  3. The credential saved in credentials.json, but only if it was saved for the same deployment as the selected API target. Otherwise skyportalai config show reports a credential conflict. Run skyportalai logout and sign in again to fix it.

The Python SDK reads only SKYPORTALAI_API_KEY, SKYPORTALAI_BASE_URL and SKYPORTALAI_ALLOW_INSECURE. It never reads config.yaml or credentials.json, and it ignores SKYPORTALAI_URL.

Next steps