sgpctl CLI

Overview

sgpctl is the command-line interface for managing Agentex cloud builds and deployments. It covers the same operations available through the SGP dashboard and the API/SDK, packaged for terminal workflows. The CLI is organized under sgpctl agentex-cloud with two subcommand groups:

build: submit cloud builds, list builds, stream build logs, and cancel running builds.
deploy: submit deployments, list deployments, stream deploy logs, and watch rollouts in real time.

Every command outputs structured data (JSON or Rich tables) that you can pipe into other tools or inspect directly.

Setup

Install sgpctl

Homebrew (macOS):

brew tap scaleapi/sgpctl https://github.com/scaleapi/sgpctl
brew install sgpctl

Binary download (Linux/Windows): Download the latest binary for your platform from the sgpctl GitHub releases. From the SGP monorepo: If you have the SGP repository cloned locally, you can build and install from source:

cd services/sgpctl && poetry build && pipx install --force dist/sgpctl-*.whl

Configure environment variables

All sgpctl agentex-cloud commands require three environment variables:

export SGP_API_KEY="your-api-key"
export SGP_ACCOUNT_ID="your-account-id"
export SGP_BASE_URL="https://api.your-sgp-instance.scale.com"

All three environment variables are required. Commands will fail immediately if any of them is missing.

You can add these exports to your shell profile (~/.bashrc, ~/.zshrc) or load them from a .env file in your CI pipeline.

Build commands

Build commands live under sgpctl agentex-cloud build. They let you submit new image builds, query build status, stream logs, and cancel running builds.

Submit a build

Package your agent source code and submit it for a cloud build:

sgpctl agentex-cloud build submit \
  --manifest ./manifest.yaml \
  --image-name my-agent \
  --tag v1.2.0

The submit command reads your manifest.yaml, packages the build context using prepare_cloud_build_context(), uploads the resulting tar.gz archive, and creates a build via POST /v5/builds. On success, the command prints the build details as JSON:

{
  "build_id": "8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02",
  "agent_name": "my-agent",
  "status": "queued",
  "image_name": "my-agent",
  "image_tag": "v1.2.0"
}

Options:

Flag	Description
`--manifest`, `-m`	Path to `manifest.yaml` (required)
`--image-name`, `-i`	Repository name for the built image (required)
`--tag`, `-t`	Image tag (default: `latest`)
`--agent-name`, `-n`	Agent name override (inferred from manifest if omitted)
`--build-arg`, `-b`	Build argument as `KEY=VALUE` (repeatable)
`--platform`, `-p`	Target platform (e.g. `linux/amd64`)

You can pass multiple build arguments by repeating the flag:

sgpctl agentex-cloud build submit \
  --manifest ./manifest.yaml \
  --image-name my-agent \
  --tag v1.2.0 \
  --build-arg PYTHON_VERSION=3.11 \
  --build-arg INSTALL_DEV_DEPS=false

Get build details

Retrieve the full details of a specific build:

sgpctl agentex-cloud build get 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02

Returns the build object as JSON, including status, image URL, timestamps, and associated metadata.

List builds

List recent builds, optionally filtered by agent name:

sgpctl agentex-cloud build list --agent-name my-agent --limit 10

Example output:

Build ID	Agent Name	Build Status	Image Name	Image Tag	Image URL	Created At
`8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02`	my-agent	success	my-agent	v1.2.0	registry.sgp.scale.com/…	2026-05-20 14:32:10
`6d1b4e82-f3a9-4c8b-a2e5-9d7f1b3c8a04`	my-agent	success	my-agent	v1.1.0	registry.sgp.scale.com/…	2026-05-18 09:15:43
`2c7f9a31-d5e8-4a1f-b6c3-8e2d4f7a9b01`	my-agent	failed	my-agent	v1.0.1		2026-05-17 16:22:05

Options:

Flag	Description
`--agent-name`, `-n`	Filter by agent name
`--limit`, `-l`	Maximum number of results (default: 20)
`--sort-order`	Sort direction: `asc` or `desc`

Stream build logs

Stream real-time build logs for a running or completed build:

sgpctl agentex-cloud build logs 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02

Logs are delivered via Server-Sent Events (SSE) and print to stdout as they arrive:

[2026-05-20 14:32:15] Step 1/8 : FROM python:3.11-slim
[2026-05-20 14:32:16] ---> Using cache
[2026-05-20 14:32:16] Step 2/8 : WORKDIR /app
[2026-05-20 14:32:17] Step 3/8 : COPY requirements.txt .
[2026-05-20 14:32:18] Step 4/8 : RUN pip install -r requirements.txt
[2026-05-20 14:32:45] Step 5/8 : COPY . .
[2026-05-20 14:32:46] Step 6/8 : RUN python -m compileall .
[2026-05-20 14:32:48] Step 7/8 : EXPOSE 8080
[2026-05-20 14:32:48] Step 8/8 : CMD ["python", "main.py"]
[2026-05-20 14:32:50] Successfully built a1b2c3d4e5f6
[2026-05-20 14:32:52] Successfully tagged registry.sgp.scale.com/my-agent:v1.2.0

The command exits when the build completes or the timeout is reached.

Flag	Description
`--timeout`	Maximum seconds to wait for logs (default: 300)

Cancel a build

Cancel a build that is queued or running:

sgpctl agentex-cloud build cancel 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02

The build transitions to cancelled status. Builds that have already completed cannot be cancelled.

Deploy commands

Deploy commands live under sgpctl agentex-cloud deploy. They let you submit deployments, check deployment status, stream logs, and watch rollouts.

Submit a deployment

Deploy an agent using a completed build:

sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env production \
  --build-id 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02

The submit command reads manifest.yaml and environments.yaml from the directory specified by --agent-path, then creates a deployment via POST /v5/agentex/deployments. Alternatively, specify an image directly instead of a build ID:

sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env staging \
  --image-name my-agent \
  --tag v1.2.0

Options:

Flag	Description
`--agent-path`, `-a`	Path to agent directory containing `manifest.yaml` and `environments.yaml` (required)
`--env`, `-e`	Environment key from `environments.yaml` (required)
`--build-id`, `-b`	Build ID to deploy
`--image-name`, `-i`	Image repository name (alternative to `--build-id`)
`--tag`, `-t`	Image tag (used with `--image-name`)
`--watch`, `-w`	Enter the live TUI dashboard after submitting

You must provide either --build-id or both --image-name and --tag. The command will reject the request if neither or both are specified.

Watch a deployment roll out

Pass --watch to deploy submit to enter a fullscreen Rich dashboard immediately after the deployment is created:

sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env production \
  --build-id 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02 \
  --watch

The TUI dashboard shows three sections: a status header at the top (agent name, environment, deployment ID, current status), a Kubernetes events panel on the left, and a container logs panel on the right. Both panels update in real time as the deployment progresses. The dashboard auto-refreshes and exits automatically when the deployment reaches a terminal state (healthy or failed). Press q or Ctrl+C to exit early.

Get deployment details

Retrieve the full details and events for a specific deployment:

sgpctl agentex-cloud deploy get 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05

Returns the deployment object as JSON, including status, events timeline, and configuration.

List deployments

List recent deployments:

sgpctl agentex-cloud deploy list --limit 10

Example output:

ID	Agent	Status	Namespace	Created At
`4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05`	my-agent	healthy	prod-agents	2026-05-20 14:33:00
`9e2d5f81-a3c7-4b9e-d1f4-6c8a2e5b7d03`	my-agent	healthy	staging-agents	2026-05-19 11:20:15
`1b8c3a62-f4d9-4e7c-a5b8-3d9f2c6e1a08`	support-bot	failed	prod-agents	2026-05-19 09:45:33

Options:

Flag	Description
`--limit`, `-l`	Maximum number of results (default: 20)

Streaming logs

Both build and deploy commands support log streaming, but they use different transport mechanisms.

Build logs (SSE)

Build logs stream via Server-Sent Events. The build logs command opens a persistent connection and prints each log line as it arrives:

sgpctl agentex-cloud build logs 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02 --timeout 600

The connection closes when the build completes or the timeout expires. This is useful for watching a build in progress from your terminal.

Deploy logs (cursor-paged polling)

Deploy logs use cursor-based polling. The deploy logs command fetches new log lines at a configurable interval:

sgpctl agentex-cloud deploy logs 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05

By default, the output renders in a Rich Live TUI panel that updates in place. For CI environments or piping to a file, use the --plain flag:

sgpctl agentex-cloud deploy logs 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05 --plain

In plain mode, each log line is written to stdout as a single line with no formatting, making it suitable for CI log capture or grep:

2026-05-20T14:33:24Z Starting application...
2026-05-20T14:33:25Z Loading model weights...
2026-05-20T14:33:28Z Model loaded in 3.2s
2026-05-20T14:33:28Z Health check endpoint ready
2026-05-20T14:33:28Z Listening on 0.0.0.0:8080

Options:

Flag	Description
`--poll-interval`	Seconds between log fetches (default: 2)
`--plain`	Plain text output, no TUI (recommended for CI)

Common workflows

Ship from laptop

Build an image and deploy it in one sequence:

# Submit the build
sgpctl agentex-cloud build submit \
  --manifest ./manifest.yaml \
  --image-name my-agent \
  --tag v1.2.0

# Stream logs until the build completes
sgpctl agentex-cloud build logs 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02 --timeout 600

# Deploy and watch the rollout
sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env production \
  --build-id 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02 \
  --watch

After the build completes, the deploy command with --watch gives you a live view of the rollout from start to finish.

Check what is deployed

List active deployments to see which builds are currently serving traffic:

sgpctl agentex-cloud deploy list

To get full details on a specific deployment, including the image tag and environment configuration:

sgpctl agentex-cloud deploy get 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05

Roll back to a previous build

Redeploy a known-good build by referencing its build ID:

sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env production \
  --build-id 6d1b4e82-f3a9-4c8b-a2e5-9d7f1b3c8a04 \
  --watch

This creates a new deployment using the image from the previous build. The existing deployment is replaced when the new one becomes healthy.

Tail logs on a running deployment

Stream container logs from a deployment that is already running:

sgpctl agentex-cloud deploy logs 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05

Use --plain to capture logs in a file:

sgpctl agentex-cloud deploy logs 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05 --plain > deploy.log

Next steps

API and SDK: programmatic access to builds and deployments
CI/CD with Gitea Actions: automate builds triggered by git push
Secrets: store and reference credentials used during builds and deployments

Overview

Getting Started

Infrastructure

Evaluations

Evaluation Dashboards

Tracing

Agents

Overview

Setup

Install sgpctl

Configure environment variables

Build commands

Submit a build

Get build details

List builds

Stream build logs

Cancel a build

Deploy commands

Submit a deployment

Watch a deployment roll out

Get deployment details

List deployments

Streaming logs

Build logs (SSE)

Deploy logs (cursor-paged polling)

Common workflows

Ship from laptop

Check what is deployed

Roll back to a previous build

Tail logs on a running deployment

Next steps

Overview

Getting Started

Infrastructure

Evaluations

Evaluation Dashboards

Tracing

Agents

Documentation Index

​Overview

​Setup

​Install sgpctl

​Configure environment variables

​Build commands

​Submit a build

​Get build details

​List builds

​Stream build logs

​Cancel a build

​Deploy commands

​Submit a deployment

​Watch a deployment roll out

​Get deployment details

​List deployments

​Streaming logs

​Build logs (SSE)

​Deploy logs (cursor-paged polling)

​Common workflows

​Ship from laptop

​Check what is deployed

​Roll back to a previous build

​Tail logs on a running deployment

​Next steps

Overview

Setup

Install sgpctl

Configure environment variables

Build commands

Submit a build

Get build details

List builds

Stream build logs

Cancel a build

Deploy commands

Submit a deployment

Watch a deployment roll out

Get deployment details

List deployments

Streaming logs

Build logs (SSE)

Deploy logs (cursor-paged polling)

Common workflows

Ship from laptop

Check what is deployed

Roll back to a previous build

Tail logs on a running deployment

Next steps