Skip to content

CLI Reference

Complete reference for Stardag CLI commands.

Installation

uv add stardag

pip install stardag

Global Commands

Version

stardag version

uv run stardag version

Show SDK version.

Authentication Commands

Login

stardag auth login [--registry NAME]

uv run stardag auth login [--registry NAME]

Opens browser for OAuth authentication.

Options:

  • --registry NAME - Target registry (default: from active profile)

Status

stardag auth status

uv run stardag auth status

Show current authentication status.

Refresh

stardag auth refresh

uv run stardag auth refresh

Refresh access token for current profile.

Logout

stardag auth logout

uv run stardag auth logout

Clear stored credentials.

Configuration Commands

Show Configuration

stardag config show

uv run stardag config show

Display current configuration and context.

Registry Management

List Registries

stardag config registry list

uv run stardag config registry list

Add Registry

stardag config registry add NAME --url URL

uv run stardag config registry add NAME --url URL

Example:

stardag config registry add central --url https://api.stardag.com

uv run stardag config registry add central --url https://api.stardag.com

Remove Registry

stardag config registry remove NAME

uv run stardag config registry remove NAME

Profile Management

List Profiles

stardag config profile list

uv run stardag config profile list

Add Profile

stardag config profile add NAME \
    --registry REGISTRY \
    --user USER \
    --workspace WORKSPACE \
    --environment ENVIRONMENT \
    [--default]

uv run stardag config profile add NAME \
    --registry REGISTRY \
    --user USER \
    --workspace WORKSPACE \
    --environment ENVIRONMENT \
    [--default]

Options:

  • -r, --registry - Registry name
  • -u, --user - User email
  • -w, --workspace - Workspace slug (team/company)
  • -e, --environment - Environment slug (project/stage)
  • -d, --default - Set as default profile

Example:

stardag config profile add prod \
    -r central \
    -u me@company.com \
    -w my-company \
    -e production \
    --default

uv run stardag config profile add prod \
    -r central \
    -u me@company.com \
    -w my-company \
    -e production \
    --default

Use Profile

stardag config profile use NAME

uv run stardag config profile use NAME

Set the default profile (also refreshes access token).

Remove Profile

stardag config profile remove NAME

uv run stardag config profile remove NAME

Workspace & Environment Commands

List Workspaces

stardag config list workspaces

uv run stardag config list workspaces

List workspaces you have access to.

List Environments

stardag config list environments

uv run stardag config list environments

List environments in the active workspace.

Target Root Commands

Target roots are managed under stardag environment target-roots. Changes are automatically synced to the local cache.

stardag environment target-roots list
stardag environment target-roots add <name> <uri>
stardag environment target-roots remove <name>
stardag environment target-roots set <name=uri ...>

uv run stardag environment target-roots list
uv run stardag environment target-roots add <name> <uri>
uv run stardag environment target-roots remove <name>
uv run stardag environment target-roots set <name=uri ...>

See stardag environment target-roots --help for full options (e.g. --env to target a specific environment).

Concurrency Limit Commands

Named concurrency limits cap how many tasks tagged with a given key may run concurrently across all builds in an environment. The SDK tags tasks with keys; the cap lives server-side in the registry and is enforced atomically when a task starts. Manage them with stardag concurrency-limits (or in the registry UI: workspace admin → Concurrency Limits).

stardag concurrency-limits list [--holders]
stardag concurrency-limits set <key> <max_concurrent>
stardag concurrency-limits delete <key> [--yes]
stardag concurrency-limits holders <key> [--limit N]
stardag concurrency-limits evict <key> <task_id> [--yes]

uv run stardag concurrency-limits list [--holders]
uv run stardag concurrency-limits set <key> <max_concurrent>
uv run stardag concurrency-limits delete <key> [--yes]
uv run stardag concurrency-limits holders <key> [--limit N]
uv run stardag concurrency-limits evict <key> <task_id> [--yes]

All commands accept -p/--stardag-profile and -e/--stardag-env to target a profile / environment other than the active one.

  • list — show each key and its max_concurrent (--holders adds the current holder count, one extra call per key).
  • set — create or update a limit (upsert; max_concurrent must be ≥ 1).
  • delete — remove a limit so the key becomes unlimited.
  • holders — list the RUNNING tasks currently holding slots of a key (oldest-running first), with task id/name, running-since and executor.
  • evict — record TASK_FAILED for a RUNNING holder to free leaked slots. Only evict holders whose process you know is dead: the server cannot verify liveness, so evicting a live worker leaves the cap oversubscribed until it finishes.

See stardag concurrency-limits --help for full options.

Environment Variables

All CLI behavior can be overridden with environment variables:

Variable Description
STARDAG_PROFILE Active profile name
STARDAG_API_URL Registry API URL
STARDAG_API_KEY API key (bypasses OAuth)
STARDAG_WORKSPACE_ID Workspace UUID
STARDAG_ENVIRONMENT_ID Environment UUID
STARDAG_TARGET_ROOTS JSON string of target roots
STARDAG_TARGET_ROOTS__NAME Specific target root override

Common Workflows

Initial Setup

# Add registry
stardag config registry add local --url http://localhost:8000

# Login
stardag auth login --registry local

# Create profile
stardag config profile add dev \
    -r local \
    -u me@example.com \
    -w my-workspace \
    -e development \
    --default

# Verify
stardag config show

# Add registry
uv run stardag config registry add local --url http://localhost:8000

# Login
uv run stardag auth login --registry local

# Create profile
uv run stardag config profile add dev \
    -r local \
    -u me@example.com \
    -w my-workspace \
    -e development \
    --default

# Verify
uv run stardag config show

Switch Environments

# Create multiple profiles
stardag config profile add dev -r local -u me@example.com -w my-workspace -e dev
stardag config profile add prod -r central -u me@company.com -w my-company -e prod

# Switch between them
stardag config profile use dev
stardag config profile use prod

# Or use environment variable
export STARDAG_PROFILE=prod

# Create multiple profiles
uv run stardag config profile add dev -r local -u me@example.com -w my-workspace -e dev
uv run stardag config profile add prod -r central -u me@company.com -w my-company -e prod

# Switch between them
uv run stardag config profile use dev
uv run stardag config profile use prod

# Or use environment variable
export STARDAG_PROFILE=prod

CI/CD Setup

# No interactive login needed - use API key
export STARDAG_API_URL=https://api.stardag.com
export STARDAG_API_KEY=sk_...
export STARDAG_WORKSPACE_ID=...
export STARDAG_ENVIRONMENT_ID=...

# Run builds
python my_pipeline.py