Skip to content

SDK & CLI Overview

Use SkyPortal from Python applications, automation scripts, and interactive terminal workflows with the open-source SDK and CLIs.

Requirements

Interfaces

Interface Command/import Best for
Python SDK from skyportalai import Skyportal Applications, internal tools, and Python automation
Automation CLI skyportalai Scripts, CI/CD, and stable JSON output
Interactive terminal skyportal Persistent human-driven chats and approval prompts

The agent executes server-side. SDK and CLI operations create chats, poll status, retrieve messages, and submit explicit approval decisions.

Install

python -m pip install skyportalai

With Poetry:

poetry add skyportalai

From a local clone:

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

Optional local observability agent:

python -m pip install "skyportalai[agent]"

Note

The SDK and both CLI commands are in the base package. There is no separate cli extra.

Authentication

Set a credential before using the SDK or automation CLI:

export SKYPORTAL_API_KEY="YOUR_SKYPORTAL_API_KEY"

Or use interactive login:

skyportal login

Saved credentials are stored in ~/.skyportal/credentials.json with user-only permissions on POSIX systems.

Credential safety

Never place real API keys, tokens, approval IDs, hosts, or private infrastructure details in code, logs, screenshots, issues, or docs.

Choose the right interface

Use skyportalai for programmatic and script-safe output:

skyportalai --json chat status 123
skyportalai --base-url https://app.skyportal.ai config show

Use skyportal for human-in-the-loop interactive workflows:

skyportal

Use the Python SDK for application-level integration:

from skyportalai import Skyportal

with Skyportal() as client:
    user = client.me()
    print(user.name)

Configuration precedence

Automation CLI (skyportalai)

Base URL precedence:

  1. Root --base-url option
  2. SKYPORTAL_BASE_URL
  3. SKYPORTAL_URL
  4. portal.base_url in ~/.skyportal/config.yaml
  5. Deployment saved with ~/.skyportal/credentials.json
  6. https://app.skyportal.ai

Credential precedence:

  1. SKYPORTAL_API_KEY
  2. SKYPORTAL_ACCESS_TOKEN
  3. access_token in ~/.skyportal/credentials.json

Path overrides:

Variable Purpose
SKYPORTAL_CONFIG_PATH Override YAML config path
SKYPORTAL_CREDENTIALS_PATH Override saved credentials path

Example config:

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

Python SDK (Skyportal)

Automatically resolves only:

Variable Purpose
SKYPORTAL_API_KEY API credential when api_key is omitted
SKYPORTAL_BASE_URL API root when base_url is omitted
SKYPORTAL_ALLOW_INSECURE=1 Allow trusted non-loopback HTTP target with warning

The SDK does not automatically read CLI config or credentials files.